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.

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")

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

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 格式可能与其他程序编写的文件不同。

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 )