Revision as of 15:13, 22 April 2011

Structure

OpenSimulator has a fairly complicated configuration structure based on Windows style INI files. This is to accomodate its many different uses and possible architectures.

Configuration files can include other configuration files. For instance, a standard standalone configuration will read the following INI files (you can see this order early on in the log and on the console).

OpenSimDefaults.ini (OpenSim 0.7.1-rc1 and onwards)
OpenSim.ini
config-include/Standalone.ini
config-include/StandaloneCommon.ini
config-include/CenomeCache.ini (not found on a default setup)
config-include/storage/SQLiteStandalone.ini

OpenSimDefaults.ini (on OpenSim 0.7.1-rc1 and later) and OpenSim.ini are always checked for on startup. However, the other INI files are loaded as a result of include directives within the preceding INI files.

For instance, at the bottom of the OpenSim.ini file in the [Architecture] section, there are a number of possible architectural includes. For example, a default OpenSim 0.7.1-rc1 standalone setup will have

[Architecture]
   Include-Architecture = "config-include/Standalone.ini"
   ; Include-Architecture = "config-include/StandaloneHypergrid.ini"
   ; Include-Architecture = "config-include/Grid.ini"
   ; Include-Architecture = "config-include/GridHypergrid.ini"
   ; Include-Architecture = "config-include/SimianGrid.ini"
   ; Include-Architecture = "config-include/HyperSimianGrid.ini"

Lines that start with at least one semicolon (;) are commented out and are not active in the configuration. Therefore, in this case, when OpenSimulator reads OpenSim.ini it will then go on to read config-include/Standalone.ini.

Changing Simulator Settings

A configuration file consists of a number of sections, each starting with the name of that section in brackets ([]). For instance, in OpenSim.ini.example you have (ignore the descriptive text)

[Startup]
   ; save_crashes = false
   ; crash_dir = "crashes"
   ...

[SMTP]
   ; enabled = false
   ...

[Chat]
   ; whisper_distance = 10

The config parameters follow each section. Each has the structure <parameter> = <value> (e.g. whisper_distance = 10).

In OpenSim.ini.example, if a parameter is commented out with a preceding semicolon (;), then the value in OpenSimDefaults.ini is used instead (in OpenSim 0.7.1-rc1 and later) or a default value within OpenSim itself.

To change a parameter, one would uncomment it and edit the value. For instance, if I wanted whisper distance to be 50 meters in my sim, I would change OpenSim.ini so that it had.

[Chat]
   whisper_distance = 50

When the sim was next started up, the whisper distance would be 50m, overriding any value in OpenSimDefaults.ini if it exists.

In OpenSim 0.7.1-rc1 and later, we recommend that parameters are changed in OpenSim.ini and not in OpenSimDefaults.ini. This is because various parameters are added or can change name between releases.

Aggregation and Overriding

As seen above, when multiple config files have the same section, the settings are aggregated. If a later setting has the same name as an earlier setting, then the later setting overrides the earlier setting.