= HowTo: Config-File =
[[TOC]]

The config-file is usually located in {{{bin/orxonox.ini}}}.

== Structure ==
Every config-file is subdivided into sections:
{{{
[Section1]
...

[Section2]
...

[AnotherSection]
...
}}}
The name between the brackets defines the sections name and is usually identical to a class name.

After a sectionname follows a list of values belonging to the section:
{{{
[Sectionname]
varname1=value
varname2=value
varname3=value
...
}}}

Every variable refers to a variable within Orxonox. See [wiki:doc/ConfigValueIncludes] and [wiki:howto/ConfigValue] for more information about how to create and use those values.

== Modifying a value in the config-file ==
To modify a value, just change the right side of the assignment
{{{
[Sectionname]
varname=oldvalue
}}}
into
{{{
[Sectionname]
varname=newvalue
}}}

If you restart Orxonox, the new value will be assigned to all instances of "Sectionname". If you don't want to restart Orxonox, call '''reloadConfig''' in the [wiki:doc/Shell].

== Modifying a value in the Shell ==
To change a value wihtout leaving Orxonox, open the [wiki:doc/Shell] and type:
{{{
config Sectionname varname newvalue
}}}
This will change the config-value in all existing instances of "Sectionname" and changes the entry in the config-file.

Alternatively you can use
{{{
tconfig Sectionname varname newvalue
}}}
This will only change the value in all existing instances, but not changing the config-file. Therefore the change will be lost if you restart Orxonox.

== Formatting of special types ==
Until now we denoted the new value just as ''newvalue''. For primitive types like {{{int}}} or {{{float}}} it's really that easy. But there exist more complex formattings for non-primitive types:
 * std::string: " my text with trailing spaces "
  * Put strings into quotes if you don't want trailing spaces to be striped

 * Vector2: (10, 20)
 * Vector3: (10, 20, 50)
 * Vector4: (10, 20, 50, 100)
 * Quaternion: (1, 2, 3, 4)
 * ColourValue: (0.1, 0.2, 0.3, 1.0)

 * bool: true and false (or just 1 and 0 as usual)

== Comments ==
It's possible to add comments into the config-file. They will be kept even if the file changes.

Comments are introduces by one of the following symbols:
 1. '''#'''comment in script-language style
 1. '''%'''comment in matlab style
 1. ''';'''comment in unreal tournament config-file style
 1. '''//'''comment in code style

== Whitespaces ==
If you add whitespaces to your config-file, for example like this:
{{{
[Sectionname]

varname = value
}}}
instead of
{{{
[Sectionname]
varname=value
}}}
this will have no effect, but if the file gets saved, Orxonox will strip the whitespaces.