Configuration files

Overview

Unreal Engine 3 relies on configuration files to dictate how it will function and initialize. Configuration is determined by key-value pairs, arranged in sections. One or more values can be associated with a given key.

Some variables are accessed directly by native code while others can easily be traced to UnrealScript code. Whenever a SaveConfig() or StaticSaveConfig() function is called on an object, the engine saves the variables to the indicated configuration file (unless the class has been defined to save its settings to an alternative configuration file).

Variables used by native code in the configuration file will normally have a simple section title. For instance, the first section that appears in the DefaultEngnine.ini configuration file is simply named [URL]. However, any variable used by UnrealScript code usually has a fully qualified class name which follows the format [(package).(classname)]. For instance, the [Engine.Engine] section in DefaultEngine.ini points to the Engine class stored within the Engine package. There are some exceptions to this rule, such as [WinDrv.WindowsClient] section.

Also keep in mind that the UnrealScript code compiler (UCC) uses the configuration file to determine which packages exist. Unlike the game engine, UCC only uses a small subset of the settings (mainly the [Editor.EditorEngine] section in the DefaultEngine.ini configuration file) to load packages.

The first time the engine is run, certain configuration files will most likely be missing. The default configuration file is loaded and translated into a configuration file that uses the current project name. For example DefaultEditor.ini is translated into UDKEditor.ini for the UDKGame project. The default files are no longer used after the actual configuration files are generated. However, you'll find that the default files are very useful for reference or to allow end users to reset their configuration files back to the default settings.

These default files build off of the core configuration defined in the Base files in the Engine project. This can be seen in the [Configuration] section of the default configuration files.

Engine configuration files are used for object and variable default values. User input configuration can be used for key bindings for functions such as Exec Commands.

Working with Configuration Files

File Format

Sections and Key-Value Pairs

[Section]
Key=Value

Special Characters

• + - Adds a line if that property doesn't 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 don't have to have an exact match, just the name of the property.

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:

[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

; This is a Comment
; So is this!

Creating Configuration Files

For example, if your configuration file is going to be based on the base Engine.ini configuration file, you would put the following at the top of your file:

[Configuration]
BasedOn=..\Engine\Config\BaseEngine.ini

To make additions to an existing key-value pair for a given section that is inherited from the base configuration file, use the + special character, as follows:

[Core.System]
+Extensions=mymap

To remove an existing key-value pair for a given section that is inherited from the base configuration file, use the - special character, as follows:

[Core.System]
-Extensions=umap

You shouldn't need to specify + or - if your configuration file is not based on anything.

Save Object Configurations

Declaring the Configuration File Name

class TestConfig extends Actor
   config(User);

var config int X;

function postbeginplay()
{
   X=5;
   SaveConfig();
}

When TestConfig is spawned at run time, it will set the value of X and save its configuration. The UDKUser.ini file (assuming your game is UDKGame) will be updated with the following:

[UDKGame.TestConfig]
X=5

The next time TestConfig is spawned at run time, the default value of X will be five. Even if you were to remove the PostBeginPlay() function from TestConfig, X will be set to equal the value five as long as it exists in the configuration file.

If you declare a new configuration file name, then that file will be created prefixed with your project name (UDK for UDKGame, Example for ExampleGame). The example below shows an object that declares a new configuration file and is saved in UDKUDN.ini (for UDKGame):

class TestConfig extends Actor
   config(UDN);

Variable configurations and inheritance

class TestConfigChild extends TestConfig;

function postbeginplay()
{
   X=15;
   SaveConfig();
}

When TestConfigChild is spawned at run time, the configuration for this object is saved as:

[UDN.TestConfigChild]
X=15

Dynamic vs static configuration

The following snippet saves the default value of X:

class'TestConfigChild'.default.X = 30;
class'TestConfigChild'.static.StaticSaveConfig();

The default value of X is written to the configuration file.

[UDN.TestConfigChild]
X=30

Available Configuration Files

Here is a list of configuration files available with a given project using the Unreal Engine:

• DefaultCharInfo - Default characters used by Unreal Tournament 3.
• DefaultCompat - Default compatibility look up tables.
• DefaultEditor - Default configuration for Unreal Editor.
• DefaultEditorKeybindings - Default key binds that are used within Unreal Editor.
• DefaultEditorUDK - Default UDK specific settings that are used within Unreal Editor.
• DefaultEditorUserSettings - Default user settings for Unreal Editor.
• DefaultEngine - Default configuration for Unreal Engine 3.
• DefaultEngineUDK - Default UDK specific settings that are used within Unreal Engine 3.
• DefaultGame - Default game configuration for the game running within Unreal Engine 3.
• DefaultGameUDK - Default UDK specific game configuration for the game running within Unreal Engine 3.
• DefaultInput - Default key binds that are used for the game running within Unreal Engine 3.
• DefaultInputDefaults - This is needed to be able to reset defaults when a Coalesced.ini is used.
• DefaultLightmass - Default Lightmass settings used by Lightmass.
• DefaultUI - Default user interface configuration for the game running within Unreal Engine 3.
• DefaultWeapon - Default weapon settings used by Unreal Tournament 3.
• DefaultWeaponDefaults - This is needed to be able to reset defaults when a Coalesced.ini is used.