User Tools

Site Tools


en:tutorials:retrieving_changing_config_values

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

en:tutorials:retrieving_changing_config_values [2019/03/25 14:29 (9 months ago)]
iarwain Fixed parameter to orxConfig_GetListString call
en:tutorials:retrieving_changing_config_values [2019/03/25 17:29 (9 months ago)]
Line 1: Line 1:
-====== Retrieving and Changing Config Values ====== 
  
-Configuration files contain sections and properties that describe many items in Orx. But they can also be used to track values during runtime. 
- 
-A ''​Level''​ property is a good example of a value that might be tracked and changed in your game. You could use a variable in your main code file to track variables like this, however there are advantages to moving these kinds of values to your config: 
- 
-  - All your data will remain together 
-  - You can change and test your values from one place without needing to compile 
-  - You can have various override config files for different situations, eg a debugging config, a release config etc. 
- 
-Let's work through how we can retrieve values from our configuration files and change them in memory. 
- 
- 
-===== Setting up a Property and Key Value ===== 
- 
-Begin by creating a common section for all your runtime related values. We'll call it ''​Runtime''​. Though you can call it anything you like: 
- 
-<code ini> 
-[Runtime] 
-Level = 1 
-</​code>​ 
- 
-So our ''​Runtime''​ section will contain a property called ''​Level''​ and will be set by default to ''​1''​. 
- 
-Our code can retrieve this value very easily with ''​orxConfig_GetU32'':​ 
- 
-<code c> 
- int level = 0; 
- 
- orxConfig_PushSection("​Runtime"​);​ 
- level = orxConfig_GetU32("​Level"​);​ 
- orxConfig_PopSection();​ 
-</​code>​ 
-  
-To make this reusable in your code, place it into a function: 
- 
-<code c> 
-int GetLevelFromConfig() { 
- int level = 0; 
- 
- orxConfig_PushSection("​Runtime"​);​ 
- level = orxConfig_GetU32("​Level"​);​ 
- orxConfig_PopSection();​ 
- 
- return level; 
-} 
-</​code>​ 
- 
-In the same way, we can change the value with ''​orxConfig_SetU32'':​ 
- 
-<code c> 
-void SetLevelInConfig(int newLevel) { 
- orxConfig_PushSection("​Runtime"​);​ 
- orxConfig_SetU32("​Level",​ newLevel); 
- orxConfig_PopSection();​ 
-} 
-</​code>​ 
- 
-Please note that this only changes the value in memory. Your ''​Level''​ property in your config file stored on disk is not affected. When your application is restarted, the original values are loaded back from the configuration files in your filesystem. 
- 
-If you are interested in persisting values back to disk in a separate config file, see [[en:​tutorials:​save_games|Saving Game information to the Config]]. 
- 
- 
-===== Lists of Strings ===== 
- 
-You can retrieve a value from a list of strings, floats, ints or vectors stored in your config. We'll have a go at retrieving string values. 
- 
-Change your ''​Runtime''​ section to contain a list of level titles: 
- 
-<code ini> 
-[Runtime] 
-Level = 1 
-Titles = Desert # Ocean # Mountains # Forest # City 
-</​code>​ 
- 
-If you wanted to get the third value from the list, which is Mountains, you can use: 
- 
-<code c> 
- orxConfig_PushSection("​Runtime"​);​ 
- const orxSTRING value = orxConfig_GetListString("​Titles",​ 2); 
- orxConfig_PopSection();​ 
-</​code>​ 
- 
-You can also choose a random value from the list by supplying a -1 index value: 
- 
-<code c> 
- orxConfig_PushSection("​Runtime"​);​ 
- const orxSTRING value = orxConfig_GetListString("​Titles",​ -1); 
- orxConfig_PopSection();​ 
-</​code>​ 
- 
-An alternative way to get a random value from a list is to instead use ''​orxConfig_GetString'':​ 
- 
-<code c> 
- orxConfig_PushSection("​Runtime"​);​ 
- const orxSTRING value = orxConfig_GetString("​Titles"​);​ 
- orxConfig_PopSection();​ 
-</​code>​ 
- 
- 
-===== Changing Orx Properties during runtime ===== 
- 
-Not only can you retrieve and update your own values, but also values of sections that define Orx objects (or any part of the Orx config). 
- 
-Examples of use: 
- 
-  - Changing the object that is spawned by a spawner 
-  - Changing the text of a text object for the next time it is displayed 
- 
-In the case of changing a spawner'​s object, let's say you had the following section: 
- 
-<code ini> 
-[AlienSpawner] 
-Object = MidSizeAlien 
-</​code>​ 
- 
-Change the object it uses: 
- 
-<code c> 
- orxConfig_PushSection("​AlienSpawner"​);​ 
- orxConfig_SetString("​Object",​ "​BossAlien"​);​ 
- orxConfig_PopSection();​ 
-</​code>​ 
- 
-The spawner will instantly switch to spawning out ''​BossAlien''​ objects. 
- 
-We'll leave it there. This really just scratches the surface of what is possible. You can see more config related functions available in the [[http://​orx-project.org/​orx/​doc/​html/​group__orx_config.html#​ga2a87cbbc3f57c1c95af63bb0746bb0ba|API]]. 
en/tutorials/retrieving_changing_config_values.txt ยท Last modified: 2019/03/25 17:29 (9 months ago) (external edit)