INI Utility Documentation ⚙️

This document outlines how to use the provided INI utility to manage configuration files for your project. The utility is designed to be simple and intuitive, mapping settings from an .ini file directly to properties in a C# class.

---

How It Works

The utility uses a C# attribute, [ConfigOption], to link class properties to specific sections and keys in an .ini file. When you load your settings, the ConfigLoader reads these attributes, finds the corresponding values in the INI file, and populates your settings object.

If the .ini file, a section, or a key doesn't exist, the utility will automatically create it using the default values you define in your settings class. It even writes your specified comments into the file, making it highly readable for end-users.

---

How to Use

Follow these two simple steps to integrate the utility into your project.

Step 1: Create a Settings Class

First, create a class that will hold all your configuration options. Each property in this class that you want to load from the INI file must be decorated with the [ConfigOption] attribute.

The [ConfigOption] attribute takes three parameters:

1. section (string): The name of the section in the INI file (e.g., [General]).
2. key (string): The name of the key within that section (e.g., LogLevel).
3. comment (string, optional): A descriptive comment that will be written above the key in the .ini file.

Important: You must provide a default value for each property. This value will be used and written to the file if it doesn't already exist.

Example Settings.cs file:

using System.Drawing;
using INIUtility; // Add this using directive

// Define an enum for a setting
public enum LogLevel
{
    Debug,
    Info,
    Warning,
    Error
}

public class MyPluginSettings
{
    [ConfigOption("General", "EnablePlugin", "Set to true to enable the plugin, false to disable.")]
    public bool EnablePlugin { get; set; } = true;

    [ConfigOption("General", "LogLevel", "Sets the logging detail level.")]
    public LogLevel LoggingLevel { get; set; } = LogLevel.Info;

    [ConfigOption("Display", "WelcomeMessage", "The message to display on startup.")]
    public string WelcomeMessage { get; set; } = "Welcome to my plugin!";

    [ConfigOption("Display", "TextColor", "The color of the text, stored as A,R,G,B.")]
    public Color TextColor { get; set; } = Color.FromArgb(255, 255, 255, 255);

    [ConfigOption("Performance", "UpdateInterval", "The update interval in milliseconds.")]
    public int UpdateInterval { get; set; } = 100;
}

---

Step 2: Load Your Settings

Once your settings class is defined, you need to load the values from the .ini file when your application starts. This is done with a single call to ConfigLoader.LoadSettings.

It is a common practice to store the loaded settings in a static property for easy access throughout your project. Example Main.cs file:

using Rage;
using INIUtility; // Add this using directive

public static class EntryPoint
{
    // A static property to hold your settings instance
    public static MyPluginSettings Settings { get; private set; }

    // Method called by the application/game when the plugin is loaded
    public static void Main()
    {
        // Load settings from the INI file.
        // The path is relative to your application's root directory.
        Settings = ConfigLoader.LoadSettings<MyPluginSettings>("Plugins/MyPlugin/settings.ini");

        // Now you can access your settings anywhere!
        if (Settings.EnablePlugin)
        {
            Game.LogTrivial($"Welcome message: {Settings.WelcomeMessage}");
            Game.DisplayNotification($"Text Color: {Settings.TextColor}");
        }
    }
}

---

Resulting .ini File

After running your code for the first time, the utility will generate an .ini file at the path you specified. Based on the MyPluginSettings example class, the settings.ini file will be created with the following content:

[General]
; Set to true to enable the plugin, false to disable.
EnablePlugin=True
; Sets the logging detail level.
LogLevel=Info

[Display]
; The message to display on startup.
WelcomeMessage=Welcome to my plugin!
; The color of the text, stored as A,R,G,B.
TextColor=255,255,255,255

[Performance]
; The update interval in milliseconds.
UpdateInterval=100

---

Supported Data Types

The utility supports the following data types:

• bool
• int
• float
• string
• double
• Color (as A,R,G,B)
• Enum (as the name of the enum value)

Dependencies

The utility requires the following packages:

• RagePluginHook SDK