Key Concepts

• Runtime Options are a flexible way to define configuration values for your game server.

Overview

Runtime Options are defined in C# code, along with their default values.

You can then read in (= override the default) any Runtime Option values from a base configuration file, making them easier to edit and manage than working with code files directly. For example, these are the core values like ApplicationName that stay the same across all environments.

For values that need to be applied only to certain environments, you can override the default values with environment-specific config files. For example, you might want to configure Debug level logging in your local environment, but Information level in production.

Some values are auto-injected into the Runtime Options system by our infrastructure stack. An example of this is database configuration: for your local environment, you'll most likely have an SQLite database configured, but in production, you'll use a cloud-based MySQL database. MySQL server configuration details are not known during build time and instead get passed in by the infrastructure scripts during deployment.

Finally, you can pass configuration values directly from the command line. This is handy in the local environment where you want to quickly and temporarily test a particular setting on your server without modifying the underlying config files.

Configuration Precedence

Runtime Options can be defined in multiple sources, and they have a fixed order of precedence for deciding which value gets selected.

In order of preference (top value overrides anything below):

1. Command line arguments.
2. Infrastructure-generated .yaml files that inject dynamic configuration like database endpoints, specified with METAPLAY_EXTRA_OPTIONS.
3. Manually configured .yaml files from Game.Server/Config/Options.*.yaml, specified with the METAPLAY_OPTIONS environment variable, which defaults to ./Config/Options.base.yaml;./Config/Options.local.yaml.
   1. Environment-specific configuration files:
      • Options.local.yaml for a local environment.
      • Options.dev.yaml for an environment named "dev".
      • Options.stage.yaml for the staging environment.
      • Options.prod.yaml for the production environment.
   2. Options.base.yaml for all environments.
4. Default values written into the Runtime Options class itself.

Hot-Loading

Runtime Options support hot-loading of new configuration values during runtime. File edits are automatically detected and cause the appropriate Runtime Options classes to be reloaded without the need to restart the server.

Hot-loading is controlled on a class-by-class basis - not all of the Metaplay core Runtime Options classes support hot loading. See the discussion below for how to mark a class as dynamic (i.e., hot-loadable) or static (i.e., not hot-loadable) and why you might want to make the distinction. You can easily view the value of this setting for each class in the LiveOps Dashboard, which is also discussed below.

Integrating Options into Your Own Code

We use Runtime Options extensively in the Metaplay SDK, and you can use them too. There are a few simple steps to follow if you want to add your custom options:

1. Declare an Options Class

Declaring your options and giving them default values is simple: just create a class that derives from RuntimeOptionsBase and give it the [RuntimeOptions(..)] attribute:

// All Options live in the 'MyFoo' container in .yaml files.
// Declared with isStatic==false, which enables hot-loading when input files
// change.
[RuntimeOptions("MyFoo", isStatic: false, "Configuration examples.")]
public class MyFooOptions : RuntimeOptionsBase
{
    // Declare basic variables (can be configured via .yaml files)
    public string SomeString       { get; private set; } = "default value";
    public int    Integer          { get; private set; } = 10;
    public bool   Enabled          { get; private set; } = true;
    public string AssetsBasePath   { get; private set; } = "./";
    public string GfxAssetsPath    { get; private set; } = "gfx";
    public string AudioAssetsPath  { get; private set; } = "audio";

    [MetaDescription("This `string` appears in the Dashboard as a description.")]
    public string AnotherString    { get; private set; } = "something else";

    // Computed variables cannot be defined in .yaml, but can still be
    // accessed in code and are shown in the Dashboard. Properties without
    // a setter and properties marked with [ComputedValue] are computed variables.
    public FullGfxAssetsPath => AssetsBasePath + GfxAssetsPath;
    [ComputedValue]
    public FullAudioAssetsPath     { get; private set; } // Set value in OnLoadedAsync
}

Pro tip

You should take some time to add descriptions to your options classes and their variables. These descriptions not only help to document your options in code, but they also get displayed in the LiveOps Dashboard. As shown in the example code above, a description for the options class itself can be set inside the RuntimeOptions attribute, and descriptions for individual variables can be set by using MetaDescriptions attributes. Both of these description fields support Markdown formatting.

⚠️ Heads up

Pay attention when specifying collections (arrays, lists, dictionaries) on multiple levels in Options, as they may behave unexpectedly. This is a limitation caused by the underlying .NET Configuration system.

2. Validate and Process Values

Runtime Options expose a powerful way to validate values through the OnLoadedAsync() hook. The hook is called when the game server loads in the initial configuration values. It is also called during hot-loading of new configuration values.

public class MyFooOptions : RuntimeOptionsBase
{
    public string SomeImportantValue { get; private set; } = null;

    public string FirstName          { get; private set; }
    public string LastName           { get; private set; }
    [ComputedValue]
    public string FullName           { get; private set; }

    public override Task OnLoadedAsync()
    {
        if (string.IsNullOrEmpty(SomeImportantValue))
            throw new InvalidOperationException("SomeImportantValue must be provided");

        FullName = $"{FirstName} {LastName}";

        return Task.CompletedTask;
    }
}

This hook can also be used to compute derived values, e.g., fetch secrets from external sources:

[RuntimeOptions("MySecret", isStatic: true)]
public class MySecretOptions : RuntimeOptionsBase
{
    // Source variable, configured in .yaml
    public string SecretSource { get; private set; }

    // Internal value, not shown on the dashboard
    [IgnoreDataMember] string _secretValue;

    public override Task OnLoadedAsync()
    {
        // Resolve the secret value based on the source. This Options class is only visible to
        // users after the OnLoadedAsync() has completed successfully.
        _secretValue = await ResolveSecretAsync(SecretSource);
    }
}

3. Access Your Values

Values can be accessed via the RuntimeOptionsRegistry instance:

MyFooOptions opts = RuntimeOptionsRegistry.Instance.GetCurrent<MyFooOptions>();
Debug.Log("Gfx asset path: {0}", opts.FullGfxAssetsPath);

⚠️ Heads up

If your Options class is marked as not static, then hot-loading may mean that the value returned changes from call to call. If you were to cache these values in some part of your code but not others, you may encounter sync issues. Derived values (as described above) are a good solution to this problem. Think carefully about how you will handle this in your code before marking your class as isStatic = false.

4. Configuring Options

To configure your option values in .yaml files, you'll need to use the name of the class followed by the name of the value. For example, the following options:

[RuntimeOptions("MyFoo", isStatic: false)]
public class MyFooOptions : RuntimeOptionsBase
{
    [EnvironmentVariable("MY_ENV_VAR")]
    public string SomeString       { get; private set; } = "default value";

    [CommandLineAlias("-MyFoo")]
    public bool   Enabled          { get; private set; } = true;
}

...could be configured with:

# Options.xxx.yaml:
MyFoo:
  SomeString: some string value
  Enabled: false

Setting values from the command line is also possible:

dotnet run --MyFoo:SomeString="some string value" -MyFoo=false

As is setting values with the environment variables:

MY_ENV_VAR="some string value" Metaplay_MyFoo__Enabled=false dotnet run

Pro Tip

The default environment variable for each property is Metaplay_ followed by the path to the property using underscores (__) as the path separator. For example, Player.DebugConfig.ServerConsistencyChecks becomes Metaplay_Player__DebugConfig__ServerConsistencyChecks and System.ClientPorts[0] becomes Metaplay_System__ClientPorts__0.

Viewing Options on the LiveOps Dashboard

With multiple configuration sources and derived values, the flexibility of the Runtime Options system can seem overwhelming. Luckily, the LiveOps Dashboard provides a handy place where you can check what values your game server is running with.

On this page are a series of expandable sections. Each tab corresponds directly to a single Runtime Options class in the server code. Expanding a section shows you the configuration values for that Runtime Options class and their descriptions. All Runtime Options classes are automatically visible in the Dashboard.