Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

ConfigFile

继承: RefCounted < Object

用于处理 INI 样式文件的辅助类。

描述

该辅助类可用于使用 INI 样式格式在文件系统上存储 Variant 值。存储的值由一个小节和一个键标识:

[section]
some_key=42
string_example="Hello World3D!"
a_vector=Vector3(1, 0, 2)

存储的数据可以被保存到文件中或从文件中解析出来,尽管 ConfigFile 对象也可以直接使用而无需访问文件系统。

以下示例显示了如何创建一个简单的 ConfigFile 并将其保存在磁盘上:

# 创建新的 ConfigFile 对象。
var config = ConfigFile.new()

# 存储一些值。
config.set_value("Player1", "player_name", "Steve")
config.set_value("Player1", "best_score", 10)
config.set_value("Player2", "player_name", "V3geta")
config.set_value("Player2", "best_score", 9001)

# 将其保存到文件中(如果已存在则覆盖)。
config.save("user://scores.cfg")

该示例展示了如何加载上面的文件:

var score_data = {}
var config = ConfigFile.new()

# 从文件加载数据。
var err = config.load("user://scores.cfg")

# 如果文件没有加载,忽略它。
if err != OK:
    return

# 迭代所有小节。
for player in config.get_sections():
    # 获取每个小节的数据。
    var player_name = config.get_value(player, "player_name")
    var player_score = config.get_value(player, "best_score")
    score_data[player_name] = player_score

任何改变 ConfigFile 的操作,例如 set_valueclear、或 erase_section,只会改变加载到内存中的内容。如果要将更改写入文件,则必须使用 savesave_encrypted、或 save_encrypted_pass 保存更改。

请记住,小节和属性名称不能包含空格。保存和加载时将忽略空格后的任何内容。

ConfigFiles 还可以包含以分号(;)开头的手动编写的注释行。解析文件时将忽略这些行。请注意,保存 ConfigFile 时注释将丢失。注释对于专用服务器配置文件仍然很有用,如果没有明确的用户操作,这些文件通常永远不会被覆盖。

注意:为 ConfigFile 指定的文件扩展名对其格式或行为没有任何影响。按照惯例,此处使用 .cfg 扩展名,但 .ini 等任何其他扩展名也有效。由于 .cfg.ini 都不是标准化的格式,Godot 的 ConfigFile 格式可能与其他程序编写的文件不同。

方法

void

clear ( )

String

encode_to_text ( ) const

void

erase_section ( String section )

void

erase_section_key ( String section, String key )

PackedStringArray

get_section_keys ( String section ) const

PackedStringArray

get_sections ( ) const

Variant

get_value ( String section, String key, Variant default=null ) const

bool

has_section ( String section ) const

bool

has_section_key ( String section, String key ) const

Error

load ( String path )

Error

load_encrypted ( String path, PackedByteArray key )

Error

load_encrypted_pass ( String path, String password )

Error

parse ( String data )

Error

save ( String path )

Error

save_encrypted ( String path, PackedByteArray key )

Error

save_encrypted_pass ( String path, String password )

void

set_value ( String section, String key, Variant value )


方法说明

void clear ( )

移除配置的全部内容。


String encode_to_text ( ) const

获得该配置文件的文本版本(与写入文件的文本相同)。


void erase_section ( String section )

删除指定小节以及其中的所有键值对。如果该小节不存在,则会引发错误。


void erase_section_key ( String section, String key )

删除小节中的指定键。如果该小节或键不存在,则会引发错误。


PackedStringArray get_section_keys ( String section ) const

返回指定小节中所有已定义键标识符的数组。如果该小节不存在,则会引发错误并返回一个空数组。


PackedStringArray get_sections ( ) const

返回所有已定义小节的标识符的数组。


Variant get_value ( String section, String key, Variant default=null ) const

返回指定小节和键的当前值。如果该小节或键不存在,则该方法返回后备值 default。如果未指定 default 或将其设置为 null,则会引发一个错误。


bool has_section ( String section ) const

如果指定的小节存在,则返回 true


bool has_section_key ( String section, String key ) const

如果指定的小节-键对存在,则返回 true


Error load ( String path )

加载指定为参数的配置文件。解析文件的内容并将其加载到调用该方法的 ConfigFile 对象中。

成功时返回 @GlobalScope.OK;如果操作失败,则返回其他 Error 值。


Error load_encrypted ( String path, PackedByteArray key )

加载指定为参数的加密配置文件,使用提供的 key 对其解密。解析文件的内容并将其加载到调用该方法的 ConfigFile 对象中。

成功时返回 @GlobalScope.OK;如果操作失败,则返回其他 Error 值。


Error load_encrypted_pass ( String path, String password )

加载作为参数的加密配置文件,使用提供的 password 解密。该文件的内容被解析并加载到调用该方法的 ConfigFile 对象中。

成功时返回 @GlobalScope.OK;如果操作失败,则返回其他 Error 值。


Error parse ( String data )

将传递的字符串解析为配置文件的内容。该字符串被解析并加载到调用该方法的 ConfigFile 对象中。

成功时返回 @GlobalScope.OK;如果操作失败,则返回其他 Error 值。


Error save ( String path )

ConfigFile 对象的内容保存到指定为参数的文件中。输出文件使用 INI 样式的结构。

成功时返回 @GlobalScope.OK;如果操作失败,则返回其他 Error 值。


Error save_encrypted ( String path, PackedByteArray key )

使用提供的 keyConfigFile 对象的内容保存到作为参数指定的 AES-256 加密文件中。输出文件使用 INI 样式的结构。

成功时返回 @GlobalScope.OK;如果操作失败,则返回其他 Error 值。


Error save_encrypted_pass ( String path, String password )

ConfigFile 对象的内容保存到作为参数指定的 AES-256 加密文件中,使用提供的 password 进行加密。输出文件使用 INI 风格的结构。

成功时返回 @GlobalScope.OK;如果操作失败,则返回其他 Error 值。


void set_value ( String section, String key, Variant value )

为指定小节的指定键赋值。如果小节或键不存在,则创建它们。如果指定的键存在,传递 null 值就会移除指定的键,如果键被移除后,小节最终是空的,就会移除小节。