Configuration Files

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.

Unreal Engine (UE) 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
Copy full snippet

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;
	};
Copy full snippet

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
Copy full snippet

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
Copy full snippet

Per-Instance Configurations

Unreal Engine 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 [Project Directory]/Saved/Config/[Platform]/[Category].ini.

The below file hierarchy example is for the Engine category of configuration files.

1. Engine/Config/Base.ini

1. Engine/Config/BaseEngine.ini
2. Engine/Config/[Platform]/base[Platform]Engine.ini
3. [Project Directory]/Config/DefaultEngine.ini
4. Engine/Config/[Platform]/[Platform]Engine.ini
5. [Project Directory]/Config/[Platform]/[Platform]Engine.ini

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
Copy full snippet

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 an entry from the property (but it has to be an exact match).
• . - Adds a new entry to the property regardless of whether that entry already exists..
• ! - Clears all entries from the property. The line must still have an = but what comes after it is ignored.

	[/Script/Engine.PlayerInput]
	Bindings=(Name="Q",Command="Foo")
	.Bindings=(Name="Q",Command="Bar")
	.Bindings=(Name="Q",Command="Foo")
Copy full snippet

Syntax For Arrays

The syntax for arrays in .ini files are formatted as follows:

	[Section]
	!ArrayVar=anything_since_this_just_clears_it
	+ArrayVar=first_value
	+ArrayVar=second_value
	+ArrayVar=third_value
Copy full snippet

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!
Copy full snippet