Overview

An environment config tells a game client how to reach one of your game's environments: the game server's address and ports, whether the connection uses TLS, and the addresses of the environment's asset CDN and public Web API. It also holds client-side settings, such as the log levels. An environment config with no server host runs the client in offline mode, with no game server.

The SDK gets the active environment config from the IEnvironmentConfigProvider integration when MetaplayCore.InitializeForClient() initializes it. Your code can read it with IEnvironmentConfigProvider.Get(). Each kind of client has a default provider:

Client	Default environment config provider
Unity client	Named environments, edited in the Unity editor and baked into the client build. See Unity Clients.
Blazor client	The game server of the environment the client was deployed to. See Blazor Clients.
Other .NET client	None.

Any client can use a provider of your own instead. See Custom Environment Config Providers.

Unity Clients

In a Unity client, the environments are named, and you choose which one a client build connects to. The default environment config provider gives you:

• Editing of your environment configs in the Unity editor, and access to them from outside of Unity,
• Multiple CI-compatible ways to define the 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,
• Extending the environment configs with game-specific settings.

The environment configs are stored in the EnvironmentConfigs.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. A client build includes the configurations baked into a binary asset that only contains the selected environments, which by default is only the active environment.

Setup

To configure your Unity project for your environments, follow this step-by-step guide.

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

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

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

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.

Selecting the Active Environment

The quickest way to select the active environment is through the Metaplay Active Environment dropdown in the Unity toolbar. This sets the 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.

The active environment can be set in the following ways:

In Unity:

• Using the Metaplay Active Environment dropdown in the Unity toolbar.
• Using the Metaplay/Environment Configs editor window.

At build-time (see Building the Environment Configs):

• 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 MetaplayUnityEditorEnvironmentConfigBuilder.Build(string activeEnvironmentId, string[] includedEnvironmentsIds) method from your build pipeline.
• Inheriting BuildEnvironmentFilter and overriding TryGetBuildOptions() to choose what every build bakes.
• Injecting the baked file manually to the correct place.

At run-time:

• See section Including Multiple Environments in a Build.

Environment Configs Editor Window

The environment configs editor window (found in the menu Metaplay/Environment Configs) provides the following functionality:

• Use the Paste Config From Clipboard button to add an environment config copied from the Metaplay 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 Baked Configs foldout to see how the baked 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 outside the Assets folder by default and therefore won’t be included in builds. The environment configs a build needs are baked into an Assets/Resources/Metaplay/BakedEnvironmentConfigs.bytes file instead.

The Metaplay SDK does the bake 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 file does not already exist.

If MetaplayUnityEditorEnvironmentConfigBuilder.Build() is called manually from your custom build method before BuildPipeline.BuildPlayer() or the baked file is created in any other way, the automatic bake will not use the editor-set active environment. The command line argument and environment variable CI overrides will still always trigger the automatic bake, and therefore overwrite an already existing file. The SDK also automatically deletes the baked file in OnPostProcessBuild(), regardless of how it was created.

To choose what every build bakes without going through a build script, inherit BuildEnvironmentFilter and override TryGetBuildOptions(). The default implementation applies the resolution order listed above.

Including Multiple Environments in a Build

You can call MetaplayUnityEditorEnvironmentConfigBuilder.Build() 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 add custom environment-specific variables by deriving the EnvironmentConfigExtension class. Every environment holds one instance of it, which you edit in the editor window along with the rest of the environment. Put the class in shared code, as it contributes to the protocol hash.

Client builds include only the members tagged with [MetaMember]. Untagged public members are still saved in the JSON file and editable in the editor window, which makes them suitable for Editor-only settings such as credentials. In the Editor, the running client also sees only the tagged members, so a missing tag shows up before you make a build.

Assets/SharedCode/EnvironmentConfig/CustomEnvironmentConfig.cs

[Serializable]
[MetaSerializableDerived(1)]
public class CustomEnvironmentConfig : EnvironmentConfigExtension
{
    // Included in client builds
    [MetaMember(1)] public int MyExtendedInt;

    // Editor-only, left out of client builds
    public string MyEditorOnlyString;
}

Assets/Scripts/ApplicationStateManager.cs

// Reading it at runtime, in the client or in the Editor
CustomEnvironmentConfig config = IEnvironmentConfigProvider.Get().GetExtension<CustomEnvironmentConfig>();
int myInt = config.MyExtendedInt;

The runtime config has only the tagged members, so config.MyEditorOnlyString is null there, even in the Editor. Editor code, such as a build script, reads the Editor-only members from the authoring-time config:

Assets/Scripts/Editor/BuildScript.cs

// Reading an Editor-only member
MetaplayUnityEditorEnvironmentConfig environment = MetaplayUnityEditorEnvironmentConfigStore.Instance.Get("develop");
string myString = ((CustomEnvironmentConfig)environment.Extension).MyEditorOnlyString;

Blazor Clients

A Blazor client deployed with metaplay deploy webclient connects to the game server of the environment it was deployed to. The deploy writes the game server's address next to the client, and the SDK reads it when it initializes. There are no environment configs to set up or choose between, and the client needs no code or configuration for this.

The SDK decides where the client connects in this order:

1. ?offline in the page's URL runs the client in offline mode, with no game server.
2. A page connects to the game server named in the endpoints file next to it, which the deploy writes. This includes a page served from localhost or an IP address, so you can copy a deployed client's endpoints file next to a local one to run it against that environment.
3. A page served from localhost or an IP address, with an empty endpoints file or none, connects to the game server running on the same host, such as one started with metaplay dev server.
4. Any other page fails to start, and logs why.

The Endpoints File

metaplay deploy webclient writes the endpoints file as metaplay-endpoints.json, next to the client's index.html, when the project's webClients entry in metaplay-project.yaml sets endpointsFile. The SDK's blazor preset sets it. The file holds what the environment reports about its game server:

Field	Value	When left out
format	The file format, 1.	Required.
serverHost	The game server's host name.	Required.
cdnBaseUrl	The base URL of the environment's asset CDN.	Required.
serverPortForWebSocket	The game server's WebSocket port.	9380
enableTls	Whether the connection uses TLS.	true
publicWebApiUrl	The base URL of the game server's public Web API.	The SDK's default for serverHost: https://<environment>-public.<domain>/.

For example:

metaplay-endpoints.json

{
  "format": 1,
  "serverHost": "mygame-develop.p1.metaplay.io",
  "enableTls": true,
  "cdnBaseUrl": "https://mygame-develop-assets.p1.metaplay.io/"
}

A Blazor client's environment has no name to select, so ActiveEnvironmentIdOverride does not apply to it, and it has no EnvironmentConfigExtension. For named environments or game-specific settings in a Blazor client, see Custom Environment Config Providers.

Custom Environment Config Providers

If you have your own way of specifying the environment a client connects to, implement IEnvironmentConfigProvider. This works the same in any client, whatever its engine or platform: the SDK uses your implementation in place of the default one, with no registration needed. InitializeSingleton() runs once, when MetaplayCore.InitializeForClient() initializes the SDK, and GetCurrent() returns the environment config the client uses.

A .NET client that is neither a Unity client nor a Blazor client, such as a console client, has no default provider, so it always needs its own.

For example, a console client that always connects to a game server running locally:

RawClient/Program.cs

public class RawClientEnvironmentConfigProvider : IEnvironmentConfigProvider
{
    static readonly EnvironmentConfig _localhost = new EnvironmentConfig
    {
        Id = "localhost",
        DisplayName = "Local Development",
        ConnectionEndpointConfig = new ConnectionEndpointConfig
        {
            ServerHost = "localhost",
            ServerPort = 9339,
            EnableTls = false,
            CdnBaseUrl = "http://localhost:5552/",
            BackupGateways = new ServerGatewaySpec[] { },
        },
        ClientLoggingConfig = new ClientLoggingConfig { LogLevel = LogLevel.Information },
    };

    public void InitializeSingleton() { }
    public EnvironmentConfig GetCurrent() => _localhost;
}