Download the sample project here, let's use this project as the base for this tutorial.
- Reading data
Let's start with the basic, the basic is the ScriptHook native Settings object. to read data from the script default INI file we can use the following methods:
Settings.GetValueBool
Settings.GetValueFloat
Settings.GetValueInteger
Settings.GetValueKey
Settings.GetValueModel
Settings.GetValueNames
Settings.GetValueString
Settings.GetValueVector3
As you can see we have different types of return, i generally use GetValueString because its easier to handle.
Those methods require some parameters:
OptionName: Set the name of the option in the INI file
Category: Set the category where the option will be
DefaultValue: Set the default value that will be returned when the option don't exists in the INI file
You can skip the Category parameter, but its not good idea.
Remember that the structure of an INI file is something like:
[CATEGORY]
OPTION1=VALUE1
OPTION2=VALUE2
[CATEGORY2]
OPTION12=VALUE12
OPTION22=VALUE22
So, to read an string from the INI file we can use:
The same idea with Integers, floats, etc..
- Writing data
We have only one method to write data in the INI file:
Settings.SetValue
We can use any of the Reading types in this method, the method will detect and write the correct info. The params needed are:
OptionName, Category and the Value that can be one of the types listed in "Reading data" section of this tutorial.
After writing into the INI file we must use the method Save to save the info in the INI file, if the file don't exists it will be automatically created:
Settings.Save
The name of the file will be the name of the script file less .net.dll/.vb/.cs part.
In my scripts i always try to maintain all settings available in .INI file without the need of release the mod with the INI file, to do this i always check if the option exists in the INI file, if don't exists i set my default value. to do this i use an method:
This method will try to read an String from the INI, if nothing is found it will set in the INI the default value, then read it again and return the result as String.
To use i call it like this:
We can use this method to read double and integer values too, we just need to convert the result to the desired type:
To read Key value i use another method that will always return an Key:
using it:
The variable must be an Keys type:
- Another way to read and write
When i need to read and write INI file with custom names like i do in Air Combat IV where i need to read ini files that are inside folder Jets and the names are custom (armor_jet_name.ini) i use the following methods:
As you can see we need to import the System.Text to use the StringBuilder object :)
We are using windows API's to read and write data from the INI file.
This method requires that the ini file already exists, so i use this method to confirm the INI file existence before use it:
Also i use an Global string variable (iniFile) to be the INI file name that im using, you can modify the methods to add this as parameter but i prefer to use this way. You must use the entire path to determine the INI file, it can be relative:
iniFile = ".\Scripts\MyCustomINI.ini"
or absolute:
iniFile = "C:\Program Files\Rockstar Games\Grand Theft Auto IV\Scripts\MyCustomINI.ini"
both works fine :)
Example of use:
