{searchform ns=en:orx:config}

====== Config ======

This section is dedicated to the Config System, which is the "data-driven" side of [[http://orx-project.org|Orx]]. Config greatly reduces the amount of code and logic required in your project.


===== Intro =====

The config system is part of Orx's core modules. It's the main module that makes Orx a data-driven game engine.\\
As it permits to do on-the-fly tweaks and modifications, it is one of the most important modules to learn.\\
When you get comfortable with it, your development time will be drastically shortened.


Its format is basically the one used in [[wp>INI_file|INI files]]. However, some concepts such as inheritance and override have been added.\\
A couple of specific operators have also been added ((for handling lists, randoms or included files, for example)) and will be covered in the [[syntax|syntax section]].


===== Config Syntax =====

To learn about the basic syntax, how to use inheritance, how to include other config files, value types and lists, see the [[Syntax|syntax page]].

===== Main Settings =====

[[en:orx:config:settings_main:main|Main settings]] refer to config used to set up overall game properties. The config modules that belong to main are:

[[en:orx:config:settings_main:main#config_module|Config]] (settings about config), [[en:orx:config:settings_main:main#console_module|Console]], 
[[en:tutorials:command:commandnotes|Command]], [[en:orx:config:settings_main:main#clock_module|Clock]], [[en:orx:config:settings_main:main#display_module|Display]], [[en:orx:config:settings_main:main#input_module|Input]], [[en:orx:config:settings_main:main#ios_module|iOS]], [[en:orx:config:settings_main:main#locale_localization_module|Locale]], [[en:orx:config:settings_main:main#mouse_module|Mouse]], [[en:orx:config:settings_main:main#param_command_line_parameters_module|Param]], [[en:orx:config:settings_main:main#physics_module|Physics]], [[en:orx:config:settings_main:main#render_module|Render]], [[en:orx:config:settings_main:main#resource_module|Resource]], [[en:orx:config:settings_main:main#screenshot_module|Screenshot]], [[en:orx:config:settings_main:main#soundsystem_module|SoundSystem]]

===== Structure Settings =====

[[en:orx:config:settings_structure:main|Structures settings]] refer to "structures" for use in your game. Structures are objects, cameras, bodies, etc. The config modules that belong to structure are:

[[en:orx:config:settings_structure:orxanim|Animation]], [[en:orx:config:settings_structure:orxbody|Body]], [[en:orx:config:settings_structure:orxjoint|Joint]], [[en:orx:config:settings_structure:orxcamera|Camera]], [[en:orx:config:settings_structure:orxclock|Clock]], [[en:orx:config:settings_structure:orxfx|FX]], [[en:orx:config:settings_structure:orxgraphic|Graphic]], [[en:orx:config:settings_structure:orxobject|Object]], [[en:orx:config:settings_structure:orxshader|Shader]], [[en:orx:config:settings_structure:orxsound|Sound]], [[en:orx:config:settings_structure:orxspawner|Spawner]], [[en:orx:config:settings_structure:orxtext|Text]], [[en:orx:config:settings_structure:orxviewport|Viewport]], [[en:orx:config:settings_structure:orxtimelinetrack|Timeline Track]]


===== Basic information =====

When Orx is initialized, it will use the executable name to deduce the main config file name.\\
Basically it will remove the extension from your executable name, if any, and add the ''.ini'' extension: if your program is called ''MyNewGame.exe'', the main config file that will be loaded when Orx is initialized will be the ''MyNewGame.ini''.

In that file you can include as many other config files ((with any kind of extension, ''.ini'' isn't mandatory)) as you want.\\

<code c>@SomeOtherConfigFile.ini@</code>


===== Advanced information =====

The basic information above is all you need to get going with config in Orx. However, much more can be done with configuration files in your code.

You can load config files directly in code.

<code c>orxConfig_Load("MyConfigFile.cfg");</code>

Once a config file is loaded, accessing its information will be done in memory, the file won't be read from disk again unless specifically asked with calls to ''orxConfig_Load()'' or ''orxConfig_ReloadHistory()''.

You can even save the content of the config to a file, either completely or partially. Here's the function you need to call in order to do so:

<code c>orxConfig_Save("MyConfigFile.cfg", bEncrypt, MySaveFilter);</code>

''MySaveFilter'' is a callback that will be called for every section and every key to let you decide if you want to save this info to the file or not.\\
If you pass ''orxNULL'' instead of a valid callback, every single key/value pair will be saved.\\
Please note that the original comments of originally loaded files won't be saved as they're ignored during the loading and never stored in memory.

In your ''MySaveFilter'' callback, when provided with a name for a section and ''orxNULL'' as a key, it is for you to decide if you want to save some parts of this section (by returning ''orxTRUE'') or if you'd rather skip the whole section completely (by returning ''orxFALSE'').\\
In the first case, you will then be asked for each key/value pair of this section if you want to save it or not.

This filter system is very handy when you want to save partial data, like for handling save games as you'll see in [[en:tutorials:config:save_games|the savegame section]].

You can find the config module API in doxygen format via [[http://doc.orx-project.org|Orx's doxygen doc page]] or directly [[http://doc.orx-project.org/group__orx_config.html|here]].\\
We believe the API is self explanatory and shouldn't be much troublesome to learn.

Config's module use, data-wise, is thoroughly described in below sections.\\
The last section shows how to adapt it for handling save games.

There are many ways in which the config module can be helpful: for example, it already is the base for the localization module.\\
It's now up to you to find other clever ways of using it depending on your needs. =)

Most of Orx's behaviors can be controlled via the config system.\\
They can be separated in two sections: [[en:orx:config:settings_main:main|default settings]] for controlling aspects such as Display, Physics, Input, ... and [[en:orx:config:settings_structure:main|structure creation]] for controlling the creation of Objects, Sounds, Graphics, Shaders, etc...

===== Encrypting Config =====

See [[encryption|Encryption & orxCrypt program]] in order to learn how to encrypt / decrypt config, and the software tools available.