Configuration

Accessing Configuration Service

The configuration service is accessible via Core.Configuration.

Configuration Paths

Get Base Path

The base path is where your plugin's configuration files are stored:

string basePath = Core.Configuration.BasePath;

Check if Base Path Exists

bool exists = Core.Configuration.BasePathExists;

Get Configuration File Path

string configPath = Core.Configuration.GetConfigPath("config.jsonc");

This returns the full path to a configuration file by name.

Initializing Configuration Files

Initialize with Template

You can initialize a configuration file from a template. The template must be packaged in a templates folder within your plugin.

Core.Configuration.InitializeWithTemplate("config.jsonc", "config.template.jsonc"); // initialize with jsonc template
Core.Configuration.InitializeWithTemplate("config.toml", "config.template.toml"); // initialize with toml template

This method is useful when you want to ship default configuration files with your plugin. The template file will be copied to the configuration directory if the target file doesn't exist.

Initialize JSON with Model

This method creates a configuration file based on a C# class model with default values:

Core.Configuration.InitializeJsonWithModel<ConfigModel>("config.jsonc", "Main");

This will generate a JSON configuration file with the structure and default values defined in your ConfigModel class.

Initialize TOML with Model

This method creates a configuration file based on a C# class model with default values:

Core.Configuration.InitializeTomlWithModel<ConfigModel>("config.toml", "Main");

This will generate a TOML configuration file with the structure and default values defined in your ConfigModel class.

Configuring the Configuration Manager

Use the Configure method to set up the internal configuration manager with specific sources and options:

Core.Configuration.Configure(builder => {
    builder.AddJsonFile("config.jsonc", optional: false, reloadOnChange: true);
    builder.AddTomlFile("config.toml", optional: false, reloadOnChange: true);
});

The Configure method accepts an action that receives an IConfigurationBuilder, allowing you to add various configuration sources.

Working with Configuration Manager

Access the configuration manager directly:

IConfigurationManager manager = Core.Configuration.Manager;

The configuration manager implements both IConfiguration and IConfigurationBuilder, providing a unified interface for reading and building configuration.

Complete Example

Here's a complete example of setting up configuration in your plugin:

1. Define Your Configuration Model

namespace MyPlugin;

public class ConfigModel {
    public bool Enabled { get; set; } = true;
    public bool Debug { get; set; } = false;
    public int MaxPlayers { get; set; } = 32;
    public string ServerName { get; set; } = "My Server";
    public List<string> AllowedMaps { get; set; } = new List<string> { "de_dust2", "de_mirage" };
}

2. Initialize Configuration in Plugin Load

public override void Load(bool hotReload) {
    // Initialize configuration file with the model and configure hot-reload
    Core.Configuration
        .InitializeJsonWithModel<ConfigModel>("config.jsonc", "Main")
        .Configure(builder => {
            builder.AddJsonFile("config.jsonc", optional: false, reloadOnChange: true);
        });

    ServiceCollection services = new();
    services.AddSwiftly(Core).AddOptionsWithValidateOnStart<ConfigModel>().BindConfiguration("Main");
}

3. Access Configuration in Your Plugin

public class MyService {
    private readonly IOptionsMonitor<ConfigModel> _config;

    public MyService(IOptionsMonitor<ConfigModel> config) {
        _config = config;
    }

    public void DoSomething() {
        if (_config.CurrentValue.Enabled) {
            Console.WriteLine($"Server: {_config.CurrentValue.ServerName}");
            Console.WriteLine($"Max Players: {_config.CurrentValue.MaxPlayers}");
        }
    }
}

Configuration File Example

After initialization, the generated config.jsonc file will look like:

{
  "Main": {
    "Enabled": true,
    "Debug": false,
    "MaxPlayers": 32,
    "ServerName": "My Server",
    "AllowedMaps": [
      "de_dust2",
      "de_mirage"
    ]
  }
}

The configuration system supports .json, .jsonc (JSON with comments) and .toml files. Using .jsonc or .toml allows you to add helpful comments for users.

Hot-Reload Support

When you enable reloadOnChange: true in the configuration builder, changes to the configuration file will automatically reload without restarting the plugin:

builder.AddJsonFile("config.jsonc", optional: false, reloadOnChange: true);
builder.AddTomlFile("config.toml", optional: false, reloadOnChange: true);

To react to configuration changes, use IOptionsMonitor<T>:

public class MyService {
    private readonly IOptionsMonitor<ConfigModel> _config;

    public MyService(IOptionsMonitor<ConfigModel> config) {
        _config = config;

        // Subscribe to configuration changes
        _config.OnChange(newConfig => {
            Console.WriteLine("Configuration reloaded!");
        });
    }
}

Method Chaining

All configuration methods support method chaining for fluent configuration:

Core.Configuration
    .InitializeJsonWithModel<ConfigModel>("config.jsonc", "Main")
    .InitializeTomlWithModel<DatabaseConfig>("database.toml", "Database")
    .Configure(builder => {
        builder.AddJsonFile("config.jsonc", false, true);
        builder.AddTomlFile("database.toml", false, true);
    });

Reference

See IPluginConfigurationService for more details.

Configuration

On this page