Language:
Page Info
Engine Version:

Configuration Files

Choose your OS:

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 Config class specifier. This saves any properties marked with the 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 Project Settings 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

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 FConfigCache.ini. For a list of all configuration file categories, see Configuration Categories .

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 , 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

    Base.ini is usually empty.

  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

    The configuration file in the Saved directory only stores the project-specific and platform-specific differences in the stack of configuration files.

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.

. 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.

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!