FileAccess

继承: RefCounted < Object

提供用于文件读写操作的方法。

描述

这个类可以用于在用户设备的文件系统中永久存储数据,也可以从中读取数据。适用于存储游戏存档数据或玩家配置文件。

下面是一个关于如何写入和读取文件的示例:

GDScriptC#

  1. func save(content):
  2. var file = FileAccess.open("user://save_game.dat", FileAccess.WRITE)
  3. file.store_string(content)
  4. func load():
  5. var file = FileAccess.open("user://save_game.dat", FileAccess.READ)
  6. var content = file.get_as_text()
  7. return content
  1. public void Save(string content)
  2. {
  3. using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Write);
  4. file.StoreString(content);
  5. }
  6. public string Load()
  7. {
  8. using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Read);
  9. string content = file.GetAsText();
  10. return content;
  11. }

在上面的例子中,文件将被保存在数据路径文件中指定的用户数据文件夹中。

FileAccess 会在释放时关闭,超出作用于、赋值为 null 等情况都会导致释放。可以使用 close 在此之前显式关闭。在 C# 中,引用必须手动释放,可以通过 using 语句或直接调用 Dispose 方法来完成。

注意:要在导出后访问项目资源,建议使用 ResourceLoader 而不是 FileAccess,因为有些文件已被转换为特定于引擎的格式,并且它们的原始源文件可能并不存在于导出的 PCK 包中。

注意:只有当进程“正常”退出时(例如通过单击窗口管理器的关闭按钮或按 Alt + F4),文件才会自动关闭。如果在项目运行时按 F8 停止项目执行,则不会关闭文件,因为游戏进程将被杀死。可以通过定期调用 flush 来解决这个问题。

教程

属性

bool

big_endian

方法

void

close ( )

bool

eof_reached ( ) const

bool

file_exists ( String path ) static

void

flush ( )

int

get_8 ( ) const

int

get_16 ( ) const

int

get_32 ( ) const

int

get_64 ( ) const

String

get_as_text ( bool skip_cr=false ) const

PackedByteArray

get_buffer ( int length ) const

PackedStringArray

get_csv_line ( String delim=”,” ) const

float

get_double ( ) const

Error

get_error ( ) const

PackedByteArray

get_file_as_bytes ( String path ) static

String

get_file_as_string ( String path ) static

float

get_float ( ) const

bool

get_hidden_attribute ( String file ) static

int

get_length ( ) const

String

get_line ( ) const

String

get_md5 ( String path ) static

int

get_modified_time ( String file ) static

Error

get_open_error ( ) static

String

get_pascal_string ( )

String

get_path ( ) const

String

get_path_absolute ( ) const

int

get_position ( ) const

bool

get_read_only_attribute ( String file ) static

float

get_real ( ) const

String

get_sha256 ( String path ) static

BitField<UnixPermissionFlags>

get_unix_permissions ( String file ) static

Variant

get_var ( bool allow_objects=false ) const

bool

is_open ( ) const

FileAccess

open ( String path, ModeFlags flags ) static

FileAccess

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

FileAccess

open_encrypted ( String path, ModeFlags mode_flags, PackedByteArray key ) static

FileAccess

open_encrypted_with_pass ( String path, ModeFlags mode_flags, String pass ) static

void

seek ( int position )

void

seek_end ( int position=0 )

Error

set_hidden_attribute ( String file, bool hidden ) static

Error

set_read_only_attribute ( String file, bool ro ) static

Error

set_unix_permissions ( String file, BitField<UnixPermissionFlags> permissions ) static

void

store_8 ( int value )

void

store_16 ( int value )

void

store_32 ( int value )

void

store_64 ( int value )

void

store_buffer ( PackedByteArray buffer )

void

store_csv_line ( PackedStringArray values, String delim=”,” )

void

store_double ( float value )

void

store_float ( float value )

void

store_line ( String line )

void

store_pascal_string ( String string )

void

store_real ( float value )

void

store_string ( String string )

void

store_var ( Variant value, bool full_objects=false )


枚举

enum ModeFlags:

ModeFlags READ = 1

打开文件进行读取操作。光标位于文件的开头。

ModeFlags WRITE = 2

打开文件进行写操作。如果文件不存在,则创建该文件,如果存在则截断。

ModeFlags READ_WRITE = 3

打开文件用于读写操作。不截断文件。光标位于文件的开头。

ModeFlags WRITE_READ = 7

打开文件进行读写操作。如果文件不存在,则创建该文件,如果存在则截断。光标位于文件的开头。


enum CompressionMode:

CompressionMode COMPRESSION_FASTLZ = 0

使用 FastLZ 压缩方法。

CompressionMode COMPRESSION_DEFLATE = 1

使用 DEFLATE 压缩方法。

CompressionMode COMPRESSION_ZSTD = 2

使用 Zstandard 压缩方法。

CompressionMode COMPRESSION_GZIP = 3

使用 gzip 压缩方法。

CompressionMode COMPRESSION_BROTLI = 4

使用 brotli 压缩方法(仅支持解压缩)。


flags UnixPermissionFlags:

UnixPermissionFlags UNIX_READ_OWNER = 256

读取所有者比特位。

UnixPermissionFlags UNIX_WRITE_OWNER = 128

写入所有者比特位。

UnixPermissionFlags UNIX_EXECUTE_OWNER = 64

执行所有者比特位。

UnixPermissionFlags UNIX_READ_GROUP = 32

读取组比特位。

UnixPermissionFlags UNIX_WRITE_GROUP = 16

写入组比特位。

UnixPermissionFlags UNIX_EXECUTE_GROUP = 8

执行组比特位。

UnixPermissionFlags UNIX_READ_OTHER = 4

读取其他比特位。

UnixPermissionFlags UNIX_WRITE_OTHER = 2

写入其他比特位。

UnixPermissionFlags UNIX_EXECUTE_OTHER = 1

执行其他比特位。

UnixPermissionFlags UNIX_SET_USER_ID = 2048

在执行比特位上设置用户 ID 。

UnixPermissionFlags UNIX_SET_GROUP_ID = 1024

在执行位上设置组 ID。

UnixPermissionFlags UNIX_RESTRICTED_DELETE = 512

限制删除(粘性)比特位。


属性说明

bool big_endian

  • void set_big_endian ( bool value )

  • bool is_big_endian ( )

如果为 true,则文件用大端字节序读取。如果为 false,则文件以小端字节序读取。如果有疑问,请将其保留为 false,因为大多数文件都是用小端字节序编写的。

注意:big_endian 只与文件格式有关,与 CPU 类型无关。CPU 字节序不会影响写入文件的默认字节序。

注意:每当打开文件时,该选项总是被重置为 false。因此,必须在打开文件之后设置 big_endian,而不是之前。


方法说明

void close ( )

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

注意:**FileAccess** 被释放时会自动关闭,释放发生在离开作用域或被赋值为 null 时。在 C# 中,使用完后必须弃置该引用,可以使用 using 语句或直接调用 Dispose 方法。


bool eof_reached ( ) const

如果文件光标已经读到了文件末尾,则返回 true

注意:eof_reached() == false 不能用于检查是否有更多可用数据。要在有更多可用数据时循环,请使用:

GDScriptC#

  1. while file.get_position() < file.get_length():
  2. # 读取数据
  1. while (file.GetPosition() < file.GetLength())
  2. {
  3. // 读取数据
  4. }

bool file_exists ( String path ) static

如果文件存在于给定路径中,则返回 true

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

对于非静态的相对等效项,请使用 DirAccess.file_exists


void flush ( )

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

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


int get_8 ( ) const

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


int get_16 ( ) const

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


int get_32 ( ) const

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


int get_64 ( ) const

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


String get_as_text ( bool skip_cr=false ) const

String 形式返回整个文件。文本会按照 UTF-8 编码解析。

如果 skip_crtrue,解析 UTF-8 时会忽略回车符(\r,CR),因此只使用换行符(\n,LF)表示新一行的开始(Unix 规范)。


PackedByteArray get_buffer ( int length ) const

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


PackedStringArray get_csv_line ( String delim=”,” ) const

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

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

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

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

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


float get_double ( ) const

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


Error get_error ( ) const

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


PackedByteArray get_file_as_bytes ( String path ) static

将整个 path 文件内容作为 PackedByteArray 返回,无需任何解码。

如果打开文件时发生错误,则返回空的 PackedByteArray。你可以使用 get_open_error 来检查发生的错误。


String get_file_as_string ( String path ) static

将整个 path 文件内容以 String 形式返回。文本被解释为 UTF-8 编码。

如果打开文件时发生错误,则返回空 String。可以使用 get_open_error 来检查发生的错误。


float get_float ( ) const

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


bool get_hidden_attribute ( String file ) static

如果文件 hidden 属性已设置,则返回 true

注意:该方法在 iOS、BSD、macOS 和 Windows 上实现。


int get_length ( ) const

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


String get_line ( ) const

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

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


String get_md5 ( String path ) static

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


int get_modified_time ( String file ) static

返回 file 的最后修改时间,使用 Unix 时间戳格式,出错时返回 0。这个 Unix 时间戳可以用 Time 单例转换为其他格式。


Error get_open_error ( ) static

返回当前线程中最后一次 open 调用的结果。


String get_pascal_string ( )

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

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


String get_path ( ) const

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


String get_path_absolute ( ) const

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


int get_position ( ) const

返回文件光标的位置。


bool get_read_only_attribute ( String file ) static

如果文件 read only 属性已设置,则返回 true

注意:此方法在 iOS、BSD、macOS 和 Windows 上实现。


float get_real ( ) const

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


String get_sha256 ( String path ) static

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


BitField<UnixPermissionFlags> get_unix_permissions ( String file ) static

返回文件的 UNIX 权限。

注意:该方法在 iOS、Linux/BSD 和 macOS 上实现。


Variant get_var ( bool allow_objects=false ) const

返回文件中的下一个 Variant 值。如果 allow_objectstrue,则允许解码对象。

在内部,这使用与 @GlobalScope.bytes_to_var 方法相同的解码机制。

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


bool is_open ( ) const

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


FileAccess open ( String path, ModeFlags flags ) static

创建一个新的 FileAccess 对象,会根据标志来确定以写入还是读取模式打开文件。

如果打开文件失败,则返回 null 。你可以使用 get_open_error 来检查发生的错误。


FileAccess open_compressed ( String path, ModeFlags mode_flags, CompressionMode compression_mode=0 ) static

创建一个新的 FileAccess 对象,并打开一个压缩文件以进行读取或写入。

注意:open_compressed 只能读取 Godot 保存的文件,不能读取第三方压缩格式。有关解决方法,请参阅 GitHub 问题 #28999

如果打开文件失败,则返回 null。可以使用 get_open_error 来检查发生的错误。


FileAccess open_encrypted ( String path, ModeFlags mode_flags, PackedByteArray key ) static

创建一个新的 FileAccess 对象,并以写入或读取模式打开一个加密文件。需要传入一个二进制密钥来加密/解密它。

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

如果打开文件失败,则返回 null。可以使用 get_open_error 来检查发生的错误。


FileAccess open_encrypted_with_pass ( String path, ModeFlags mode_flags, String pass ) static

创建一个新的 FileAccess 对象,以写或读的模式打开一个加密文件。你需要传递一个密码来加密/解密它。

如果打开文件失败,则返回 null 。你可以使用 get_open_error 来检查发生的错误。


void seek ( int position )

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


void seek_end ( int position=0 )

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

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


Error set_hidden_attribute ( String file, bool hidden ) static

设置文件 hidden 属性。

注意:该方法在 iOS、BSD、macOS 和 Windows 上实现。


Error set_read_only_attribute ( String file, bool ro ) static

设置文件 read only 属性。

注意:该方法在 iOS、BSD、macOS 和 Windows 上实现。


Error set_unix_permissions ( String file, BitField<UnixPermissionFlags> permissions ) static

设置文件的 UNIX 权限。

注意:该方法在 iOS、Linux/BSD 和 macOS 上实现。


void store_8 ( int value )

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

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

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


void store_16 ( int value )

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

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

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

GDScriptC#

  1. const MAX_15B = 1 << 15
  2. const MAX_16B = 1 << 16
  3. func unsigned16_to_signed(unsigned):
  4. return (unsigned + MAX_15B) % MAX_16B - MAX_15B
  5. func _ready():
  6. var f = FileAccess.open("user://file.dat", FileAccess.WRITE_READ)
  7. f.store_16(-42) # 发生环绕,存储 65494 (2^16 - 42)。
  8. f.store_16(121) # 在范围内,存储 121。
  9. f.seek(0) # 回到开头,读取存储的值。
  10. var read1 = f.get_16() # 65494
  11. var read2 = f.get_16() # 121
  12. var converted1 = unsigned16_to_signed(read1) # -42
  13. var converted2 = unsigned16_to_signed(read2) # 121
  1. public override void _Ready()
  2. {
  3. using var f = FileAccess.Open("user://file.dat", FileAccess.ModeFlags.WriteRead);
  4. f.Store16(unchecked((ushort)-42)); // 发生环绕,存储 65494 (2^16 - 42)。
  5. f.Store16(121); // 在范围内,存储 121。
  6. f.Seek(0); // 回到开头,读取存储的值。
  7. ushort read1 = f.Get16(); // 65494
  8. ushort read2 = f.Get16(); // 121
  9. short converted1 = (short)read1; // -42
  10. short converted2 = (short)read2; // 121
  11. }

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_buffer ( PackedByteArray buffer )

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


void store_csv_line ( PackedStringArray values, String delim=”,” )

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

将使用 UTF-8 编码文本。


void store_double ( float value )

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


void store_float ( float value )

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


void store_line ( String line )

line 附加到文件末尾,并在后面加上一个换行符(\n),将使用 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_objectstrue,则允许编码对象(并且可能包含代码)。

在内部,这使用与 @GlobalScope.var_to_bytes 方法相同的编码机制。

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

Previous Next


© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.