UDN
Search public documentation:

ConfigurationFiles
日本語訳
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > Unreal Engine 3 Basics > Configuration files
UE3 Home > Input / Output > Configuration files

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

Typical configuration files consist of sections of key-value pairs, arranged as follows:

[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

Most people seem to be under the impression that the semicolon denotes comments in configuration files, but they aren't. 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's not actually.

; This is a Comment
; So is this!

Creating Configuration Files

When creating a new configuration file that is based on another configuration, you should include the [Configuration] section with the BasedOn key-value pair.

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

Unreal Engine 3 has the ability to save the configuration of an object to any desired configuration file. The syntax of an UnrealScript / Engine configuration file is very straight forward and easily traceable to the Object that created the entry.

Declaring the Configuration File Name

The class declaration contains the filename of the new configuration file. For example, the following example class declares that its variables will be saved to the 'User' configuration file:

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


Configuration variables are inherited by subclasses. However, if SaveConfig() is called on a child of TestConfig, the value of X is stored for the child class. The example below extends the above TestConfig class:

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

There are two different methods programmers can use to save an object's configuration to a configuration file: dynamic and static. Basically, this simply means the runtime variables are saved if you call SaveConfig() on an instance of an object. Calling StaticSaveConfig() on a class variable will write the object's default values to the configuration file. The examples above all covered saving the configuration of a run time object. This would allow you to revert the end users configuration, or to override the class's default properties defined in Unrealscript in the configuration file.

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


Configuration files are located in the Config directory for any given project (e.g %UDK_ROOT%\UDKGame\Config).

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.