Difference between revisions of "Gkini"
Ravenwolf397 (Talk | contribs) (Correct WriteString() length limit) |
Ravenwolf397 (Talk | contribs) (Improve summary, add info to ReadString section) |
||
| Line 1: | Line 1: | ||
| − | These are functions to manipulate the | + | These are functions to manipulate the game's config file config.ini, located at "INSTALL_DIR/config.ini". |
The format of the file looks like this: | The format of the file looks like this: | ||
| − | [section] | + | <source lang="ini"> |
| − | key=value | + | [section] |
| − | + | key=value | |
| − | . | + | key2=value2 |
| + | key3=value3 | ||
| + | ... | ||
| − | + | [section2] | |
| + | key4=value4 | ||
| + | key5=value5 | ||
| + | key6=value6 | ||
| + | ... | ||
| + | </source> | ||
| + | For example, here is an excerpt from one config.ini: | ||
| + | <source lang="ini"> | ||
| + | [Vendetta] | ||
| + | version=4 | ||
| + | skin=skins/platinum/ | ||
| + | maxframerate=120 | ||
| + | </source> | ||
| + | |||
| + | Values are usually strings or integers. All identifiers (sections and keys) are case-sensitive. | ||
| + | |||
| + | Each entry is exactly one line; this means they cannot contain newline characters ("\n"). The key and value are separated by the ''first'' equal sign in the line; for example, "key==value" is interpreted as a key "key" and value "=value". | ||
| + | |||
| + | All entries are limited to 767 characters (including key, equal sign, and value). Entries larger than this might be truncated, split, or ignored. | ||
| + | |||
| + | If any of your strings have a null character ("\0") in them, then they will be treated as if they ended there. So for these functions, a string like "foo\0bar" will be treated like it was just "foo". | ||
| Line 44: | Line 66: | ||
'''section''' a section of the config file<br> | '''section''' a section of the config file<br> | ||
'''key''' key within a section<br> | '''key''' key within a section<br> | ||
| − | '''default''' value to return if key not found | + | '''default''' value to return if key not found or value is empty (eg. "foo=") |
<br><br> | <br><br> | ||
'''Returns:''' | '''Returns:''' | ||
| Line 50: | Line 72: | ||
'''Example:'''<br> | '''Example:'''<br> | ||
<source lang="lua">gkini.ReadString("Vendetta", "Username", "dude") -> "hans" -- get the default username from the config file</source> | <source lang="lua">gkini.ReadString("Vendetta", "Username", "dude") -> "hans" -- get the default username from the config file</source> | ||
| + | '''Notes:'''<br> | ||
| + | - Leading/trailing spaces are stripped from the return value. For example, if your file reads "key= value ", then ReadString(section, "key", "") will return "value", not " value ".<br> | ||
| + | - If the entry is longer than 767 characters, then further characters will be ignored. | ||
<br><br> | <br><br> | ||
Revision as of 22:52, 15 April 2023
These are functions to manipulate the game's config file config.ini, located at "INSTALL_DIR/config.ini".
The format of the file looks like this:
[section] key=value key2=value2 key3=value3 ... [section2] key4=value4 key5=value5 key6=value6 ...
For example, here is an excerpt from one config.ini:
[Vendetta] version=4 skin=skins/platinum/ maxframerate=120
Values are usually strings or integers. All identifiers (sections and keys) are case-sensitive.
Each entry is exactly one line; this means they cannot contain newline characters ("\n"). The key and value are separated by the first equal sign in the line; for example, "key==value" is interpreted as a key "key" and value "=value".
All entries are limited to 767 characters (including key, equal sign, and value). Entries larger than this might be truncated, split, or ignored.
If any of your strings have a null character ("\0") in them, then they will be treated as if they ended there. So for these functions, a string like "foo\0bar" will be treated like it was just "foo".
Functions
ReadInt
Definition:
ReadInt(string section, string key, int default) -> int value
Description:
Read an integer from the given section and key
Arguments:
section a section of the config file
key key within a section
default value to return if key not found
Returns:
Example:
gkini.ReadInt("Vendetta", "showhelpstring", 1) -> 0 -- showhelpstring is ccurrently set to 0
ReadString
Definition:
ReadString(string section, string key, string default) -> string value
Description:
Read a string from the given section and key
Arguments:
section a section of the config file
key key within a section
default value to return if key not found or value is empty (eg. "foo=")
Returns:
Example:
gkini.ReadString("Vendetta", "Username", "dude") -> "hans" -- get the default username from the config file
Notes:
- Leading/trailing spaces are stripped from the return value. For example, if your file reads "key= value ", then ReadString(section, "key", "") will return "value", not " value ".
- If the entry is longer than 767 characters, then further characters will be ignored.
WriteInt
Definition:
WriteInt(string section, string key, int value) -> nil
Description:
Write an integer to the given section and key
Arguments:
section a section of the config file
key key within a section
value value of a key as an integer
Returns:
Example:
gkini.WriteInt("Vendetta", "showhelpstring", 1) -- change the showhelpstring option to 1
WriteString
Definition:
WriteString(string section, string key, string value) -> nil
Description:
Write a string to the given section and key. The entire entry must be <= 767 characters in total, including the key, equals sign, and value. If the entry is longer than this, then it will be truncated to 767 characters.
Arguments:
section a section of the config file
key key within a section
value value of a key as a string
Returns:
Example:
gkini.WriteString("Vendetta", "Username", "dude") -- change the Username option to dude
