Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

ConfigFile¶

Inherits: RefCounted < Object

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

Description¶

该辅助类可用于使用 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")

// 创建新的 ConfigFile 对象。
var config = new ConfigFile();

// 存储一些值。
config.SetValue("Player1", "player_name", "Steve");
config.SetValue("Player1", "best_score", 10);
config.SetValue("Player2", "player_name", "V3geta");
config.SetValue("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

var score_data = new Godot.Collections.Dictionary();
var config = new ConfigFile();

// 从文件加载数据。
Error err = config.Load("user://scores.cfg");

// 如果文件没有加载，忽略它。
if (err != Error.Ok)
{
    return;
}

// 迭代所有小节。
foreach (String player in config.GetSections())
{
    // 获取每个小节的数据。
    var player_name = (String)config.GetValue(player, "player_name");
    var player_score = (int)config.GetValue(player, "best_score");
    score_data[player_name] = player_score;
}

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

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

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

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

Methods¶

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 )