Gkini

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:

<source lang="ini"> [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". Empty ("") section names will work correctly, empty keys will not.

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: configured value, or default if not present/empty

Example:
<source lang="lua">gkini.ReadInt("Vendetta", "showhelpstring", 1) -> 0 -- showhelpstring is currently set to 0</source>

ReadInt2

Unknown

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: configured value, or default if not present/empty

Example:
<source lang="lua">gkini.ReadString("Vendetta", "Username", "dude") -> "hans" -- get the default username from the config file</source> 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 ". This appears to apply only to space characters, and does not include tabs ("\t").
- If the entry is longer than 767 characters (including key, equal sign, and value), then further characters will be ignored.

ReadString2

Definition:
ReadString2(string section, string key, string default, string file) -> string value

Description:
Read a string from the given section and key, from any .ini file.

Arguments:
section a section of the config file
key a key of the config file
default value to return if entry is not present
file path to the config file to read from (relative to VO install directory)

Returns: Configured value, or default if not present/empty

Example:
<source lang="lua">gkini.ReadString2("foo", "bar", "", "plugins/myplugin/settings.ini") -> "baz" -- read the foo/bar entry from plugins/myplugin/settings.ini</source> Notes:
- Essentially identical to ReadString, except for the fourth argument allowing you to specify the file from which to read.
- There is no paired "WriteString2" function; you can only write configuration to the game's config.ini file, nowhere else.

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: nil

Example:
<source lang="lua">gkini.WriteInt("Vendetta", "showhelpstring", 1) -- change the showhelpstring option to 1</source>

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: nil

Example:
<source lang="lua">gkini.WriteString("Vendetta", "Username", "dude") -- change the Username option to dude</source> Notes:
- value=nil is accepted without error, but appears to do nothing.
- Unlike ReadString, leading and trailing spaces are not trimmed from values.
- Newline and equal sign characters are accepted without escaping or translation. This means you can do, for example, WriteString(section, "foo", "bar\n\n[baz]x=13") and get <source lang="ini"> foo=bar

[baz] x=13 </source> Note that this also moves the keys after "foo" to the "bar" section. For this reason, it is generally wise to avoid providing newlines or equal signs to WriteString. (This includes key; WriteString(section, "key=", "value") will create a line "key==value", which will be interpreted by ReadString as "key" and "=value", not "key=" and "value".)