---
title: Plugin Configs
description: Documentation on how to use launcher-provided apis to make your plugin configurable
published: true
date: 2025-07-07T14:52:39.459Z
tags: 
editor: markdown
dateCreated: 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:

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

---

## Declaring a Config Class

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

```csharp
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

```csharp
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:

```csharp
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:

```csharp
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:

```csharp
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.