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 according to the version of Metaplay SDK you're currently using.

Metaplay release 29 and later

1. Go to portal.metaplay.dev and select Projects -> View Project.

2. Click the Export Unity Configs button to open up the export dialog.

3. Click the Copy to clipboard button to copy all the available game client configs (for environments which are currently online, and which you're a member of).

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

5. Click the Paste Config From Clipboard button. After a confirmation message, you should now see the configs you copied in the environments list in the editor window.

Metaplay releases 26.1 to 28

Older versions of the Metaplay SDK do not support the batch import/export of environment configurations. You'll have to perform the following steps for each individual environment:

1. Go to portal.metaplay.dev and select Projects -> View Project -> View Environment.

2. Select the Configure Client tab.

3. At the bottom of the tab, click the Copy to clipboard as JSON button.

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

5. Click the Paste Config From Clipboard button. After a confirmation message, you should now see the configs you copied in the environments list in the editor window.

Your environments are now configured in the client! The environment configurations are stored in the EnvironmentConfigs.json file, found by default in the ProjectSettings/Metaplay/ 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.

At run-time:

• See section Including Multiple Environments in a Build

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 init-time by providing the ActiveEnvironmentIdOverride in MetaplayClientOptions when calling MetaplayClient.Initialize. This sets an override that is in effect for the runtime of the app or until changed.

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.