| 19 | | == Macros == |
| 20 | | |
| 21 | | * '''!SetConfigValue('''''varname''''', '''''defvalue''''')''': Defines a new config-value with a default value. ''varname'' must be a member-variable of a class and the macro should only be used in the setConfigValues() function of this class to allow ingame-changes of the values. A description can be set by adding '''.description('''''string''''')''' at the end of the macro. |
| 22 | | * '''!ResetConfigValue('''''varname''''')''': Sets the given config-value back to the default value. |
| 23 | | |
| 24 | | == Example == |
| 25 | | |
| 26 | | Definition of a class in the header-file: |
| 27 | | {{{ |
| 28 | | #!cpp |
| 29 | | class MyClass : public BaseObject |
| 30 | | { |
| 31 | | public: |
| 32 | | MyClass(); // Constructor |
| 33 | | void setConfigValues(); // Inherited function |
| 34 | | |
| 35 | | const std::string& getName() |
| 36 | | { return this->name_; } |
| 37 | | |
| 38 | | float getVersion() |
| 39 | | { return this->version_; } |
| 40 | | |
| 41 | | private: |
| 42 | | std::string name_; |
| 43 | | float version_; |
| 44 | | }; |
| 45 | | }}} |
| 46 | | |
| 47 | | Implementation of the class source-file: |
| 48 | | {{{ |
| 49 | | #!cpp |
| 50 | | MyClass::MyClass() |
| 51 | | { |
| 52 | | // Macro call to create an Identifier |
| 53 | | RegisterObject(MyClass); |
| 54 | | |
| 55 | | // Function call to assign the config-values to the new object |
| 56 | | this->setConfigValues(); |
| 57 | | } |
| 58 | | |
| 59 | | void MyClass::setConfigValues() |
| 60 | | { |
| 61 | | SetConfigValue(name_, "Orxonox").description("The name of the game"); |
| 62 | | SetConfigValue(version_, "1.0").description("The version-number"); |
| 63 | | } |
| 64 | | }}} |
| 65 | | |
| 66 | | Extract of orxonox.ini: |
| 67 | | {{{ |
| 68 | | [MyClass] |
| 69 | | name_="Orxonox" |
| 70 | | version_=1.1 // We have changed this value from 1.0 to 1.1 |
| 71 | | }}} |
| 72 | | |
| 73 | | Some other code: |
| 74 | | {{{ |
| 75 | | #!cpp |
| 76 | | MyObject orxonoxobject; |
| 77 | | std::cout << "Name: " << orxonoxobject.getName() << std::endl; |
| 78 | | std::cout << "Version: " << orxonoxobject.getVersion() << std::endl; |
| 79 | | }}} |
| 80 | | |
| 81 | | Output: |
| 82 | | {{{ |
| 83 | | Name: Orxonox |
| 84 | | Version: 1.1 |
| 85 | | }}} |
| 86 | | |
| 87 | | == The config-file == |
| 88 | | |
| 89 | | The config-file (usually ''orxonox.ini'') has a clear structure, split into sections, where each section belongs to one class. A new section is introduced by a line containing the name of the class in square brackets: |
| 90 | | {{{ |
| 91 | | [ClassName] |
| 92 | | }}} |
| 93 | | The following lines contain all config-values of the class in the following form: |
| 94 | | {{{ |
| 95 | | varname=value |
| 96 | | }}} |
| 97 | | |
| 98 | | The config file adds missing variables or sections and repairs unreadable values by resetting them to the default value, but it doesn't change or remove needless entries. This allows you to add comments or funny ASCII-art. Whitespaces are ignored, so you can format your config-file in every way you like. |
| 99 | | |
| 100 | | You can begin a line with a comment-symbol to ignore a line. If this removes an entry, a new one gets added to the end of the section, but you could add two versions of a line and comment one (for example when you want to test different settings without losing the previous value). There are four different comment-symbols: |
| 101 | | * '''#'''comment: script-language style |
| 102 | | * '''%'''comment: matlab style |
| 103 | | * ''';'''comment: unreal tournament config-file style |
| 104 | | * '''//'''comment: code style |
| 105 | | |
| 106 | | Different variable-types have different formattings in the config file. There are three different cases: |
| 107 | | * '''Primitives''': varname=value |
| 108 | | * '''Strings''': varname="string" |
| 109 | | * '''Complex types''' (like vectors): varname=(value1, ..., valueN) |
| 110 | | |
| 111 | | * Additionally booleans can be denoted by using ''true'' or ''false''. |
| 112 | | |
| 113 | | There are four cases causing the parser to change the config-file: |
| 114 | | 1. Case: A config-value is set, but can't be parsed (wrong formatting) or can't be converted to the wanted type: |
| 115 | | * Change: The value is set back to the default |
| 116 | | 1. Case: A config-value is missing but the section of the corresponding class exists: |
| 117 | | * Change: The value is added at the end of the section |
| 118 | | 1. Case: The whole section is missing or can't be found because the [!ClassName]-line is missing: |
| 119 | | * Change: The whole section is added at the end of the file |
| 120 | | 1. Case: The config-file is missing: |
| 121 | | * Change: The config-file is created and all sections and values are written to the file. |
| 122 | | |
| 123 | | Example of a valid config-file: |
| 124 | | {{{ |
| 125 | | [MyClass] <-- This name is stupid |
| 126 | | firstValue_ = 1.000000 |
| 127 | | secondValue_ = 1.0 |
| 128 | | thirdValue_ = 1 |
| 129 | | |
| 130 | | [OtherClass] <-- This name is even worse |
| 131 | | //teststring = "test" |
| 132 | | teststring = "teeeeeeeeeeeest" |
| 133 | | |
| 134 | | [StupidNamedClass] <-- This name rocks |
| 135 | | position1_=(1.0, 2.0, 3.0) |
| 136 | | position2_ = ( 1.000000 , 2.000000 , 3.000000 ) |
| 137 | | position3_ = (1,2,3) |
| 138 | | |
| 139 | | gagagugubleeeeeeeeeep! |
| 140 | | |
| 141 | | [LastClass] <-- Where did you know...? Now this is scary... |
| 142 | | moo_ = "Oh yes they do!" |
| 143 | | bTheyMoo_ = true |
| 144 | | }}} |
| | 17 | See [wiki:ConfigValueIncludes] for more information about how to create and modify different types of config-values. |
