Availability: Public Title: Configuration Files Crumbs: %ROOT%, Engine, Programming, Programming/Basics Description:Text files containing property settings for configuring gameplay or engine behavior. Version: 4.5 [TOC (start:2 end:3)] ## Overview Configuration files can be used to set values for properties that will be initialized when the project is loaded. Configuration is determined by key-value pairs, arranged in sections. One or more values can be associated with a given key. Engine configuration files are used for object and variable default values. User input configuration can be used for key bindings. By default, `DefaultEngine.ini` and `DefaultGame.ini` are created when you create a new blank project with the **Project Wizard**. New projects that begin with templates may also generate `DefaultEditor.ini` and `DefaultInput.ini` configuration files if needed. The `SaveConfig()` function can be called on a class with the [](Programming\UnrealArchitecture\Reference\Classes\Specifiers\Config) class specifier. This saves any properties marked with the [](Programming\UnrealArchitecture\Reference\Properties\Specifiers\Config) property specifier to the appropriate configuration file. Generally, variables saved by `SaveConfig()` are in a section title which follows the format **[(package).(classname)]**. For instance, the **[/Script/Engine.Engine]** section in `DefaultEngine.ini` points to the Engine class stored within the Engine package. There are some exceptions with hard-coded section names. A number of the settings previously available only through editing configuration files are available in Unreal Editor in the [](Engine\UI\ProjectSettings) editor. ## Specifying Configurable Variables In order to specify which variables should be read in from configuration files, the class that contains those variables must first be given the `Config` specifier in its `UCLASS` macro. UCLASS(Config=Game) class AExampleClass : public AActor [REGION:tip] Note that a category (i.e. Game) must be supplied for the `Config` specifier. This determines which configuration files the class's variables are read from and saved to. All possible categories are defined in `FConfigCacheIni`. For a list of all configuration file categories, see [Configuration Categories](#configurationcategories). [/REGION] Decorating a class with the `Config` specifier just indicates that that class can have variables read in from configuration files, and specifies which files the configurations are read from. To specify a particular variable as read in and saved to a configuration file, the `Config` specifier must also be supplied to a `UPROPERTY()` macro. UCLASS(Config=Game) class AExampleClass : public AActor { GENERATED_UCLASS_BODY() UPROPERTY(Config) float ExampleVariable; }; No category is supplied to the property's `Config` specifier. The `ExampleVariable` property can now be read from any `Game` configuration file in the [configuration file hierarchy](#filehierarchy), as long as the information is specified with the following syntax: [/Script/ModuleName.ExampleClass] ExampleVariable=0.0f ### Config Files and Inheritance The `Config` `UCLASS` and `UPROPERTY` specifiers are inherited. This means that a child class can either read in or save out all variables specified as `Config` in the parent class, and they will be in the same configuration file category. The variables will all be under a section title with the child class's name. For example, the configuration file information for a `ChildExampleClass` which inherits from the `ExampleClass` above would look like the following lines, and be saved in the same `Game` configuration files. [/Script/ModuleName.ChildExampleClass] ExampleVariable=0.0f ### Per-Instance Configurations Unreal Engine 4 has the ability to save the configuration of an object to any desired configuration file. If the `PerObjectConfig` specifier is used in the `UCLASS` macro, configuration information for this class will be stored per instance, where each instance has a section in the `.ini` file named after the object in the format `[ObjectName ClassName]`. This keyword is propagated to child classes. ## Configuration File Structure Each configuration category has its own hierarchy of files which specify engine-specific, project-specific, and platform-specific configurations. ### Configuration Categories * Compat * DeviceProfiles * Editor * EditorGameAgnostic * EditorKeyBindings * EditorUserSettings * Engine * Game * Input * Lightmass * Scalability ### File Hierarchy The configuration file hierarchy is read in starting with `Base.ini`, with values in later files in the hierarchy overriding earlier values. All files in the `Engine` folder will be applied to all projects, while project-specific settings should be in files in the project directory. Finally, all project-specific and platform-specific differences are saved out to `[ProjectDirectory]/Saved/Config/[Platform]/[Category].ini` The below file hierarchy example is for the `Engine` category of configuration files. 1. `Engine/Config/Base.ini` [REGION:tip] `Base.ini` is usually empty. [/REGION] 1. `Engine/Config/BaseEngine.ini` 1. `Engine/Config/[Platform]/[Platform]Engine.ini` 1. `[ProjectDirectory]/Config/DefaultEngine.ini` 1. `[ProjectDirectory]/Config/[Platform]/[Platform]Engine.ini` 1. `[ProjectDirectory]/Saved/Config/[Platform]/Engine.ini` [REGION:tip] The configuration file in the `Saved` directory only stores the project-specific and platform-specific differences in the stack of configuration files. [/REGION] ## Working with Configuration Files ### File Format #### Sections and Key-Value Pairs Typical configuration files consist of sections of key-value pairs, arranged as follows: [Section] Key=Value #### Special Characters * *+* - Adds a line if that property does not exist yet (from a previous configuration file or earlier in the same configuration file). * *-* - Removes a line (but it has to be an exact match). * *.* - Adds a new property. * *!* - Removes a property; but you do not have to have an exact match, just the name of the property. [REGION:note] **Note**: **.* is like *+** except it will potentially add a duplicate line. This is useful for the bindings (as seen in `DefaultInput.ini`), for instance, where the bottom-most binding takes effect, so if you add something like: [/Script/Engine.PlayerInput] Bindings=(Name="Q",Command="Foo") .Bindings=(Name="Q",Command="Bar") .Bindings=(Name="Q",Command="Foo") It will work appropriately. Using a *+* there would fail to add the last line, and your bindings would be incorrect. Due to configuration file combining, the above usage pattern can happen. [/REGION] #### Comments Most people seem to be under the impression that the semicolon denotes comments in configuration files, but they are not (`FConfigFile::ProcessInputFileContents` does not actually treat them, or any other string, as a comment delimiter). This behavior is intentional. Technically any character can represent a different key-value pair. Typically, a semicolon is placed at the beginning of a new line. It works like a comment, but it is not actually. ; This is a Comment ; So is this!