Introduction to Pluggy INI Files

The latest version of Pluggy supports the use of INI config files. This article gives a brief overview of INI files and their usage.

What is an INI?

The INI file is the most common type of file for storing configuration settings in the MS Windows environment. The basic elements of the INI file are as follows.

Sections

A section is denoted by a name in square brackets ([]). Sections are used primarily for the organization of data within the file, so that it is easier to find information when viewing an INI file in a text editor. For example, if I wanted to create an INI that stored detailed information about the player's character, I might want to use some of these sections to keep the file organized:

[General]
[Attributes]
[Skills]
[Spells]
[Equipped Items]

Keys

The key is where the actual information is stored within the INI file. With the functions available in Pluggy, we can read and store 4 types of data:

• Integers
• Floats
• References, stored as FormIDs
• Strings

Each key has a name, with an equals sign (=) separating the key's name from the key's value. We can now expand our INI file about the player with actual data:

[General]
Name=Sir Rupert the Lame
Level=9
Gold=1489

[Attributes]
Health=248.3

 ...

[Spells]
ActiveSpell=000A97DF

[Equipped Items]
Weapon=00000C0D

Comments

Like in Oblivion Scripting, comments are denoted by a semicolon (;) at the start of the commented text. Expanding our INI file again with comments, we now have:

[General]
;Name is a string
Name=Sir Rupert the Lame
;Lvl & gold are ints
Level=9
Gold=1489

[Attributes]
;Health is a float
Health=248.3

 ...

[Spells]
;StandardFireDamageTarget1Novice ("Fireball")
ActiveSpell=000A97DF

[Equipped Items]
;WeapIronShortSword ("Iron Shortsword")
Weapon=00000C0D

When should I use an INI?

Generally, any time that you want to use a list of settings that can be modified outside of the game. INI files could also be used as a means to store data in an organized manner, allowing players to share information (such as data about their character, in the above examples) or settings with friends.

INI vs. RunBatchScript

Many people are already using files to load settings via the OBSE function RunBatchScript - why then would you want to use INI files? Well, they have several advantages.

• Data is more organized, so it's easier for players to understand what they're looking at when editing the file.
• The "KeyName=Value" syntax of INIs simple and more direct than the "set SomeVariable to Value" scripting commands needed by RunBatchScript
• The IniRead___ functions require you to give them a default value which is used if a key is invalid or the player has accidentally damaged the INI file.
  • Because of the default values, less code is needed to check the loaded data for errors; simply go ahead and use the default values.
• The IniWrite___ functions can be used to update any values that may have changed via an ingame setup menu or etc. There's simply no way to do this with RunBatchScript.

Relevant Functions

See each function's page for more information about its syntax and usage.

Loading Data

• IniReadInt
• IniReadFloat
• IniReadRef
• IniReadString

Saving to File

• IniWriteInt
• IniWriteFloat
• IniWriteRef
• IniWriteString

Other INI functions

• IniKeyExists
• IniDelKey

Examples

Loading Data From INI

Going back to the previous example INI, the following script can be used to load data from the INI into Oblivion:

;Variables where the data will be stored
long name
long level
long gold
float health
ref spell
ref weapon

;Variables needed to feed the IniRead___ functions
long file
long section
long key

;Variables for default values
long dInt
float dFloat
ref dRef

...

set file to CreateString -1 "myConfigFile.ini"
set section to CreateString -1 "General"
set key to CreateString -1 "Name"

set name to CreateString
set dInt to CreateString -1 "Unknown Name"
IniReadString name file section key dInt

DestroyString dInt

SetString key "Level"
set dInt to -1
set level to IniReadInt file section key dInt

SetString key "Gold"
set gold to IniReadInt file section key dInt

SetString section "Attributes"
SetString key "Health"
set dFloat to -1
set health to IniReadFloat file section key dFloat

SetString section "Spells"
SetString key "ActiveSpell"
set dRef to 0
set spell to IniReadRef file section key dRef

SetString section "Equipped Items"
SetString key "Weapon"
set weapon to IniReadRef file section key dRef

DestroyString file
DestroyString section
DestroyString key

Saving Data to INI

Again using the example INI, this script could be used to update the values in the INI with the player's current information:

;Variables to feed the IniWrite___ functions
long file
long section
long key

;Temp variables to hold data before it is saved
long tempL
float tempF
ref tempR

...

set file to CreateString -1 "myConfigFile.ini"
set section to CreateString -1 "General"
set key to CreateString -1 "Name"

set tempL to CreateString
StringGetName player tempL
IniWriteString file section key tempL

DestroyString tempL

SetString key "Level"
set tempL to player.GetLevel
IniWriteInt file section key tempL

SetString key "Gold"
set tempL to player.GetGold
IniWriteInt file section key tempL

SetString section "Attributes"
SetString key "Health"
set tempF to player.GetAV health
IniWriteFloat file section key tempF

SetString section "Spells"
SetString key "ActiveSpell"
set tempR to GetPlayerSpell
IniWriteRef file section key tempR

SetString section "Equipped Items"
SetString key "Weapon"
set tempR to player.GetEquippedObject 9
IniWriteRef file section key tempR

DestroyString file
DestroyString section
DestroyString key