Overview

Environment Configs are a convenient way to define your environment-specific configurations. Currently, the environment config system is implemented only for client-side configuration, with server-side and more to come.

The SDK gets the environment info it needs, notably the ServerEndpoint, from the active IEnvironmentConfigProvider implementation. By default, DefaultEnvironmentConfigProvider is used. You can also implement a custom environment config provider to provide the environment configs from a custom source.

Setup

To configure your Unity project for your environments, follow this step-by-step guide (Metaplay release 26.1 and later):

1. Navigate to your environment in the Metaplay developer portal. Go to portal.metaplay.dev, select Projects -> View Project -> View Environment -> Game Server -> Game Client Configs.

2. Click the Copy to clipboard as JSON button to copy the game client configuration.

3. Open your Unity project and open the Metaplay environment configs editor from the menu Metaplay/Environment Configs.

   

4. Click the Paste Config From Clipboard button.

   

   You should now see the environment you copied in the environments list in the editor window.

5. Repeat these steps for each of your environments.

Your environments are now configured in the client! The environment configurations are stored in the EnvironmentConfigs.json file, found by default in the Assets/Resources/Metaplay/Editor folder. If you edit the EnvironmentConfigs.json file outside of Unity, remember to bring the changes to the editor window by clicking the Refresh Editor From File button.

You can use the environment configs editor's Active Environment dropdown to select your active environment. In the next section, we'll show you multiple ways to select your active environment when making client builds.

Default Environment Config Provider

The features of the default environment config provider include:

• Easy editing of your environment configs and easy access to them from outside of Unity,
• Easily extendable and customizable,
• Multiple CI-compatible ways to define your active environment for your client builds,
• Filtering of sensitive data out of client builds,
• Support for multiple environments in client builds and overriding the active environment at runtime,

The default environment config provider (DefaultEnvironmentConfigProvider) stores the environment configs in a JSON file, which you can edit with a text editor or with the built-in Unity editor window found in the Metaplay/Environment Configs menu. A default file that includes the offline and localhost environments will be created automatically if none is found.

The master JSON file is built into separate build-included JSON files that only contain a filtered version of selected environments, which by default is only the active environment. Setting the active environment is easy from both the editor and from CI pipelines. The DefaultEnvironmentConfigProvider's active environment can be set in the following ways:

In Unity:

• Using the Metaplay/Environment Configs editor window

At build-time:

• Passing it as a command line argument to Unity (example: -MetaplayActiveEnvironmentId=offline).
• Setting the environment variable METAPLAY_ACTIVE_ENVIRONMENT_ID to the chosen environment ID.
• Calling the DefaultEnvironmentConfigProvider.Instance.BuildEnvironmentConfigs(string activeEnvironmentId, string[] includedEnvironmentsIds) method from your build pipeline.
• Injecting the built files manually to the correct place.

Environment Configs Editor Window

Here are the functionalities you can access through the environment configs editor window (found in the menu Metaplay/Environment Configs):

• Use the Active Environment dropdown to select the active environment used in editor Play Mode and for manual builds from the editor, if the build's active environment isn't defined in another way (See section Building the Environment Configs).
• Use the Paste Config From Clipboard button to add an environment config copied from the developer portal (See the section Setup)
• Use the Refresh Editor From File button after editing the JSON file outside Unity to bring the changes to Unity. Note that interacting with the editor window's config inspector automatically saves changes to the JSON file.
• Use the Preview Built Configs foldout to see how the filtered environment config included in client builds will look. The preview only includes the active environment.
• Use the editor as a handy way to edit your environment configs and add new environments.

Building the Environment Configs

The master JSON file is under an editor folder by default and therefore won’t be included in builds, so environment configs must be built into a BuildEnvironmentConfigs.json file and a BuildActiveEnvironmentId.txt file. The DefaultEnvironmentConfigBuilder does the build automatically in OnPreprocessBuild using:

• Primarily, the command line argument -MetaplayActiveEnvironmentId=, if found.
• Secondarily, the environment variable METAPLAY_ACTIVE_ENVIRONMENT_ID, if found.
• Thirdly, the editor-set active environment ID, but only if the files do not already exist.

If DefaultEnvironmentConfigProvider.Instance.BuildEnvironmentConfigs is called manually from your custom build method before BuildPipeline.BuildPlayer or the built environment config files are created in any other way, the automatic build will not use the editor-set active environment. The command line argument and environment variable CI overrides will still always trigger the automatic environment config build, and therefore overwrite any already existing files. DefaultEnvironmentConfigBuilder also automatically deletes the built files in OnPostProcessBuild, regardless of how they were created.

Including Multiple Environments in a Build

You can call DefaultEnvironmentConfigProvider.Instance.BuildEnvironmentConfigs from your custom build method before invoking the Unity client build to specify the active environment and the environment configs to include in the build. Including multiple environments in a build allows changing environments at runtime by calling DefaultEnvironmentConfigProvider.Instance.SetActiveEnvironmentId and restarting the app for the set environment to become active. Calling SetActiveEnvironmentId at runtime sets the runtime active environment override that is stored in PlayerPrefs. The runtime active environment override takes priority over the active environment ID loaded from file.

Extending Environment Configs

You can derive the EnvironmentConfig class to add custom environment-specific variables (see the example in Idler: CustomExtendedEnvironmentConfig). Additionally, you can override EnvironmentConfig.FilterForClientBuild to customize the filtering of the environment configs.

// Example custom environment config class
public class CustomExtendedEnvironmentConfig : EnvironmentConfig
{
    // Custom environment specific variable
    public int MyExtendedInt;

    // Override the filter method to filter out custom environment specific variables from being included in client builds
    protected override void FilterForClientBuild()
    {
        base.FilterForClientBuild();
        // We don't want to include the value of MyExtendedInt in client builds, so we reset it here
        MyExtendedInt = -1;
    }
}

Implementing a Custom Environment Config Provider

You can implement IEnvironmentConfigProvider or derive DefaultEnvironmentConfigProvider to customize provider behavior or the source of the environment configs. The IntegrationRegistry system will automatically use the most derived implementation, or the one outside the SDK assembly. See Release 25 Environment Configs Migration Guide for compatibility with our old systems.