# 配置文件

此文为configurationcategories (opens new window)的原创翻译,本文内容版权归原文所有,仅供学习,如需转载望注本文地址,翻译不易,谢谢理解。

包含配置gameplay或者引擎行为属性设置值的文本文件。

在工程加载时,配置文件可以被用来给一些需要初始化的类属性设置值,配置文件中有按模块排放键值对,一个或者更多的值可通过一个给定的键关联。

引擎配置文件用来存放对象或变量的默认值,用户输入配置可用作键绑定,默认地,DefaultEngine.ini和DefaultGame.ini是在你使用工程向导创建空白工程的时候创建的。创建于模板的新工程也会在需要的时候生成DefaultEditor.ini和DefaultGame.ini文件。

SaveConfig()函数可以被有Config类说明符的类调用,这会将被Config属性说明符标记的任何属性保存到配置文件。一般地,被SaveConfig()标记的变量值会被保存到一个区域,它的区域名称格式是[(package).(classname)]。比如,DefaultEngine.ini中[/Script/Engine.Engine]的区域会指向引擎包里的引擎类,当然还有一些硬编码的区域名除外。

之前只能通过编辑配置文件来进行的设置现在可以在编辑器中的项目设置面板进行配置。

# 指定可配置变量

为了指定哪些变量应该从配置文件中读值,首先应该在包含这些变量的类的UCLASS宏中使用Config说明符修饰。

UCLASS(Config=Game)
class AExampleClass : public AActor
1
2

注意,在Config说明符中必须要提供一个分类,比如上面的Game,这决定了类的变量应该从哪读然后保存到哪。所有可能的分类都在FConfigCache.ini文件中定义了,要得到完整的配置文件分类,请看下面。

使用Config说明符来修饰一个类只是表明该类有变量从配置文件中读值,然后指定从哪个配置文件中读,为了说明该类的哪个特定变量会从配置文件读写,需要在UPROPERTY()宏中使用Config说明符。

UCLASS(Config=Game)
class AExampleClass : public AActor
{
GENERATED_UCLASS_BODY()

UPROPERTY(Config)
float ExampleVariable;

};
1
2
3
4
5
6
7
8
9

在属性的Config说明符中不用指定分类,上面的ExampleVariable属性应该从配置文件层级中的任何Game配置文件读取,只要在配置文件中以下面的语法提供:

[/Script/ModuleName.ExampleClass]
ExampleVariable=0.0f
1
2

# 配置文件和继承

Config,UCLASS,UPROPERTY说明符是会被继承的。这意味着一个子类可以读或者保存所有在父类中被Config修饰的变量,他们也会在同一个配置目录中。变量将会在以子类名命名的区域中。举例来说,继承ExampleClass的ChildExampleClass的配置文件信息将会像下面这样,同样被保存在同样的Game配置文件中。

[/Script/ModuleName.ChildExampleClass]
ExampleVariable=0.0f
1
2

# 每个实例的配置

UE4有能力保存一个对象的配置信息到任何想要的配置文件。如果在UCLASS宏中使用PerObjectConfig说明符,这个类的配置信息将会按每个实例形式保存,每个实例在.ini文件中都会有一个区域,以[ObjectName ClassName]形式保存,这个关键字会被子类继承。

# 配置文件结构

每个配置分类都有它自己的层级文件,会指定引擎相关,项目相关和平台相关的配置信息。

# 配置目录

  • Compat
  • DeviceProfiles
  • Editor
  • EditorGameAgnostic
  • EditorKeyBindings
  • EditorUserSettings
  • Engine
  • Game
  • Input
  • Lightmass
  • Scalability

# 文件层级

配置文件的层级在读的时候以Base.ini开始,层级后面文件中的值会覆盖前面的。在引擎目录中的所有文件会被应用到所有项目里,尽管项目相关的设置应该被保存在项目目录中的文件,最后,所有项目相关和平台相关的不同会被保存到[ProjectDirectory]/Saved/Config/[Platform]/[Category].ini。

下面以引擎类别的配置文件的文件层级为例:

  1. Engine/Config/Base.ini(该文件通常为空)
  2. Engine/Config/BaseEngine.ini
  3. Engine/Config/[Platform]/[Platform]Engine.ini
  4. [ProjectDirectory]/Config/DefaultEngine.ini
  5. [ProjectDirectory]/Config/[Platform]/[Platform]Engine.ini
  6. [ProjectDirectory]/Saved/Config/[Platform]/Engine.ini

Saved目录中的配置文件只存储项目相关和平台相关的不同。

# 配置文件约定

# 格式

配置文件应该包含一个区域名字和相应的键值对。比如

[Section]
Key=Value
1
2

# 特殊字符

  • + : 如果这个属性在层级较低的文件或同样的文件中还不存在,添加一行。
  • - : 移除一行,它需要准确地匹配。
  • . : 添加一个新的属性。
  • ! : 移除一个属性,你不用准确匹配,只需指定属性名字。

注意"."就像"+"一样,但它可能会添加重复的一行,这在键绑定的时候会比较有用,可在DefaultInput.ini中看到,举例来说,一般最后的绑定会起作用,所以你需要添加如下内容:

[/Script/Engine.PlayerInput]
Bindings=(Name="Q",Command="Foo")
.Bindings=(Name="Q",Command="Bar")
.Bindings=(Name="Q",Command="Foo")
1
2
3
4

它会正常地工作,在这里使用+将不能添加最后一行,而且你的绑定也是不对的,由于配置文件的结合,上面的用法会经常出现。

# 注释

在配置文件中,大部分人的感觉是分号表示注释,但并不是这样的,FConfigFile::ProcessInputFileContents并不会将分号和任何其他字符视为注释分隔符,这是有意为之的,从技术上来说,任何字符都可以代表一个不同的键值对,典型地,一个分号被放在一个新行的开头,它就像注释一样工作,但它实际并不是。

# 蓝图与配置文件

蓝图中的变量也可以从配置文件中读取,但需要在变量的细节面板勾选Config Variable。

ConfigVariable

可以将鼠标移动到Config Variable处查看配置文件信息,以及要写入配置文件的区域名称。

TipInfo

# 注意点

  • 不管是蓝图还是C++在程序运行时需要以Standalone Game模式运行,否则不会从配置文件中读取变量值。
  • 蓝图中将变量设置为可配置变量,会在UE4启动时从相应的配置文件读取到蓝图里,但是并不会自动更新到场景中该蓝图实例化的对象里,一般在蓝图中修改这些变量值,其场景中的实例化对象会跟着改变。
  • 修改蓝图中的变量值,在关闭时并不会保存到配置文件中,下次打开工程该蓝图中的变量值依旧会从配置文件中读取。

# 扩展阅读

  1. CustomSettings (opens new window)
  2. UE4中Config的使用 (opens new window)