wiki/se-launcher/development/plugin-configs.md

title, description, published, date, tags, editor, dateCreated

title	description	published	date	tags	editor	dateCreated
Plugin Configs	Documentation on how to use launcher-provided apis to make your plugin configurable	true	2025-07-07T14:52:39.459Z		markdown	2025-07-07T14:52:37.701Z

Plugin Configs

While you can implement your own configuration system for your plugin, it is highly recommended to use the built-in configuration system provided by SE Launcher. This system offers centralized storage, a unified format, and seamless integration with the plugin lifecycle.

---

Using the Built-in Config System

The launcher provides a utility class called ConfigHandler, which can be used to register and manage your plugin's configuration files.

You can retrieve an instance of ConfigHandler via the game service provider:

var handler = MySandboxGame.Services.GetRequiredService<ConfigHandler>();

---

Declaring a Config Class

Here’s a simple example of a configuration class with one setting:

public class Config
{
    public string UserName { get; set; } = "John";
}

The class must be public, have a parameterless constructor, and its properties must be publicly gettable and settable to be properly handled by the configuration system.

---

Plugin Example with Config Usage

using CringePlugins.Config;
using Microsoft.Extensions.DependencyInjection;
using NLog;
using Sandbox;
using VRage.Plugins;

namespace TestPlugin;

public class Plugin : IPlugin
{
    private static readonly Logger Log = LogManager.GetCurrentClassLogger();

    public void Dispose()
    {
    }

    public void Init(object gameInstance)
    {
        Log.Info("Test Plugin init");

        var handler = MySandboxGame.Services.GetRequiredService<ConfigHandler>();
        using var config = handler.RegisterConfig<Config>("test");
        
        Log.Info("Hello, {UserName}", config.Value.UserName);
    }

    public void Update()
    {
    }
}

Explanation

• RegisterConfig<T>(string id) registers a config and returns a ConfigReference<T>.
• The returned .Value contains the current config instance.
• This reference automatically reflects changes made to the config from other plugins or future disk reloads (disk reloading is not yet implemented, but planned).

---

Updating Config

If your config class is mutable (as in the example), changing a property like this:

config.Value.UserName = "NewName";

will not automatically persist the changes.

To update and save the configuration, you need to assign a new instance to the .Value property:

config.Value = new Config
{
    UserName = "NewName"
};

This ensures that the new value is persisted to disk and broadcast to other consumers of the same config.

---

Managing Config Lifetime

The ConfigReference<T> returned by RegisterConfig must be disposed when no longer needed. This releases associated resources and unhooks change tracking.

In the example above, the config is used only during Init() and disposed immediately with a using block.

If you need to access the config during the whole plugin lifetime, store the reference in a field, and dispose of it inside the Dispose() method:

private ConfigReference<Config>? _config;

public void Init(object gameInstance)
{
    var handler = MySandboxGame.Services.GetRequiredService<ConfigHandler>();
    _config = handler.RegisterConfig<Config>("test");
    
    Log.Info("Welcome, {UserName}", _config.Value.UserName);
}

public void Dispose()
{
    _config?.Dispose();
}

This approach ensures that your plugin holds the configuration safely throughout its lifecycle and disposes of it properly when the game or plugin is closed.