This is an old revision of the document!
As well as loading information from a config file, you can also save your own sections back to a seperate config file.
This can be used to persist score or player information to a file that can be loaded when the player returns to your game.
There is currently no specific guide on this page to take you through the process. In lieu of that, the following link takes you to the API where you can get familiar with what config functions are available for working with config files:
http://orx-project.org/orx/doc/html/group__orx_config.html
You might be able to glean some usage examples from this project file:
Look for the LoadSavedHighScores and SaveHighScoresToConfig functions.
Also, make sure you don't miss the detail outlined on the Config page
Hopefully a proper tutorial can be put together soon. If you'd like to write one, please feel free to replace this page.
.
.
.
.
.
.
.
The following is draft information, pending release.
As well as loading information from a config file, you can also save the content of config in memory to a file, either completely or partially.
This can be used for all manner of things like persisting scores, player information or any game information to a file that can be loaded back later.
Here's the function you need to call in order to do so:
orxConfig_Save(“MySavedConfigFile.ini”, bEncrypt, MySaveFilterCallback);
The first parameter is the filename you wish to save your config to. The extension can be anything you like. I usually just stick to ini
.
The second parameter indicates if the file is to be written encrypted so that it won't be human readable.
The last parameter 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.
Let's work through an example.
Just say we had an initial config loaded by your game that was something like this:
[Input] SetList = KeysForInput
[KeysForInput] KEY_ESCAPE = Quit
[Mouse] ShowCursor = true
[Display] ScreenWidth = 1024 ScreenHeight = 768
When your Orx game loads, this config would be loaded into memory.
You can then add to the config that is in memory. To add something like a highscore value to the config in memory, we could do it with:
if(orxConfig_PushSection(“SaveSettings”)) {
orxConfig_SetS64("HighScore", score); orxConfig_PopSection();
}
This would be added to the config and memory and the entire result would be:
[Input] SetList = KeysForInput
[KeysForInput] KEY_ESCAPE = Quit
[Mouse] ShowCursor = true
[Display] ScreenWidth = 1024 ScreenHeight = 768
[SaveSettings] HighScore = 53281
We could save the entire config in memory to an external file with:
orxConfig_Save(“MySavedConfigFile.ini”, orxFALSE, orxNULL);
Rarely would you be dumping the entire config. In our case, we only want to save the SaveSettings section to disk.
This is where the callback filter comes into play.
In your MySaveFilter callback (which is called many times by orxConfig_Save), the section and keys are provided.
It is for you to decide, in code, if you want to save some parts of this section to be saved (by returning orxTRUE) or if you'd rather skip the whole section completely (by returning orxFALSE).
This may not be very clear, so lets look at an example callback:
orxBOOL orxFASTCALL MySaveFilterCallback(const orxSTRING _zSectionName, const orxSTRING _zKeyName, const orxSTRING _zFileName, orxBOOL _bUseEncryption) {
// Return orxTRUE for the section "SaveSettings", orxFALSE otherwise // -> filters out everything but the "SaveSettings" section return ( orxString_Compare(_zSectionName, "SaveSettings") == 0 ) ? orxTRUE : orxFALSE;
}
This will filter out all the config sections that are in memory, except for the SaveSettings
section. So if you call:
orxConfig_Save(“MySavedConfigFile.ini”, orxFALSE, MySaveFilterCallback);
Then only the SaveSettings
section will appear in your MySavedConfigFile.ini file.
Of course, to load your save file back, simply do a:
orxConfig_Load(“MySavedConfigFile.ini”);
That should be enough to get you going, creating save files for your games.
In order to save only a particular key from a config (instead of saving all keys from a config, we need to change our callback. Let's say our SaveSettings
sections contained two keys:
[SaveSettings] HighScore = 53281 LastLevel = 6
If we only wanted the LastLevel
key to be saved with the section out to the file, the callback would look like this:
orxBOOL orxFASTCALL MySaveFilterCallback(const orxSTRING _zSectionName, const orxSTRING _zKeyName, const orxSTRING _zFileName, orxBOOL _bUseEncryption) {
// Filters out everything but "SaveSettings" section. // And only the "LastLevel" key for the "SaveSettings" section. return ( orxString_Compare(_zSectionName, "SaveSettings") == 0 && (_zKeyName == orxNULL || orxString_Compare(_zKeyName, "LastLevel") == 0) ) ? orxTRUE : orxFALSE;
}
In the code above, compare to the section name to get the SaveSettings
. The comparing of _zKeyName to orxNULL will get the section name. Then the comparing to LastLevel
will get the specific key.
There is a lot more that the config API can do. You can get familiar with what config functions are available at:
http://orx-project.org/orx/doc/html/group__orx_config.html
There are some usage examples in the Orx Curve Editor that is undergoing development at: https://bitbucket.org/sausage/orx-curvefx-editor
Also, make sure you don't miss the detail outlined on the Config page