配置文件系统
Configuration Files
UE 的 .ini 配置按类别(Engine、Game、Input……)分层加载:从引擎 Base 文件到项目 Default 文件,再到平台文件和用户文件,后加载的同名键覆盖先加载的。数组可以用 +、-、! 等运算符跨层增删。UCLASS(config=X) 加上 UPROPERTY(Config) 可以让类的默认值从 ini 自动读取;命令行 -ini: 可以临时覆盖。
层级与覆盖
配置文件是按节 (section) 组织的键值对,在引擎启动时为所有构建和平台设置对象与属性的默认值。同一类别的文件形成层级,同名键时后加载的覆盖先加载的。Engine 目录下的文件对所有使用该引擎的项目生效,项目目录下的只对该项目生效,<PLATFORM> 目录下的只对该平台生效。(Configuration Files in Unreal Engine)
官方给出的类别加载顺序(以某一类别 <CATEGORY> 为例):
flowchart TD A["Engine/Config/Base.ini"] --> B["Engine/Config/Base类别.ini"] B --> C["引擎平台 Base 文件<br/>Base平台类别.ini"] C --> D["项目 Config/Default类别.ini"] D --> E["引擎平台文件 平台类别.ini"] E --> F["项目平台文件 平台类别.ini"] F --> G["用户文件 User类别.ini<br/>(本地应用数据、我的文档、项目)"]
上图从上到下依次加载,越往下优先级越高:项目 Default 文件覆盖引擎 Base 文件,平台文件再覆盖 Default 文件,最后是用户级文件。完整规则见引擎源码 ConfigHierarchy.h。(Configuration Files in Unreal Engine)官方建议尽量改项目目录下的配置,以便更精细地控制。
数组运算符
| 运算符 | 含义 | 例 |
|---|---|---|
! | 清空数组 | !MyArray=ClearArray |
+ | 值不存在时追加 | +MyArray=Value |
- | 移除该值 | -MyArray=Value |
. | 追加,允许重复 | .MyArray=Value |
(Configuration Files in Unreal Engine)这样可以跨多层文件往同一个数组里添加条目,例如在 BaseEngine.ini 和项目的 DefaultEngine.ini 中分别追加。
自动读入类属性
节名写成 [/Script/ModuleName.ClassName](类名不带 U/A 前缀),类声明为 UCLASS(config=Game),属性标记 UPROPERTY(Config),然后在该类别层级中的任意文件(如 DefaultGame.ini)里赋值即可。(Configuration Files in Unreal Engine)这依赖 UObject 与反射系统 提供的属性元数据。复制驱动类(复制图)就是通过 DefaultEngine.ini 配置的例子。
调试与覆盖
- 有控制台命令可以查看任意配置值,包括其他平台的配置。
- 命令行
-ini:<CATEGORY>:[SECTION]:<KEY>=<VALUE>可以临时覆盖配置,但不支持数组。(Configuration Files in Unreal Engine)
开发者设置 (Developer Settings)
UDeveloperSettings 是「所有自动发现的设置对象的基类」,位于 Runtime 模块 DeveloperSettings(头文件 Engine/DeveloperSettings.h),是一个抽象 UCLASS。派生类会被自动注册到设置界面,引擎自带的 UNetworkSettings、URendererSettings、UAssetManagerSettings、UGameFeaturesSubsystemSettings 等都继承自它。(UDeveloperSettings (API))
| 虚函数 | 作用(官方说明) |
|---|---|
GetContainerName() | 设置容器:Project(项目设置)或 Editor(编辑器偏好) |
GetCategoryName() | 高层分类,如 Editor、Engine、Game |
GetSectionName() | 唯一节名,默认用类的 FName |
GetSectionText() / GetSectionDescription() | 显示名和描述,默认取类的 DisplayName 和 ToolTip |
SupportsAutoRegistration() | 是否自动注册;返回 false 则自行注册 |
GetCustomSettingsWidget() | 自定义界面,仅限非常特殊的情况 |
OnSettingChanged() 委托可以监听属性修改。带 ConsoleVariable 元数据的属性可以用 ImportConsoleVariableValues / ExportValuesToConsoleVariables 与控制台变量同步;UDeveloperSettingsBackedByCVars 适用于部分或全部设置存放在控制台变量而非 config 变量的情况。不用自动注册时,可以调用 ISettingsModule::RegisterSettings(Container, Category, Section, ...) 手动注册(5.7 API)。(UDeveloperSettings (API))属性值本身仍然通过上文的 UCLASS(config=...) + UPROPERTY(Config) 机制从 ini 读写(这是归纳)。
出处
- Configuration Files in Unreal Engine UE 5.8 文档
- UDeveloperSettings (API) UE 5.8 API 参考