Breaking changes

• MetaplayClientOptions, which is passed to MetaplayClient.Initialize from userland code, and MetaplaySDKConfig have been refactored, with some variables removed (ConnectionOptions, LoggingOptions, DebuggingOptions) and others moved within the inner classes.
• The parameters that have been removed are now supplied by IEnvironmentConfigProvider internally in MetaplaySDK.Start, MetaplayClientState.DefaultCreatePlayerContext, MetaplayClientState.OnSharedGameConfigUpdated and in MetaplayConnection.CreateConnection.
• ConnectionConfig and ConnectionDelegate have been moved from MetaplayClientOptions.MetaplayConnectionOptions to MetaplayClientOptions.
• Other removed variables are now in EnvironmentConfig.
• The removed parameters that were hard-coded to the call of MetaplayClient.Initialize can be hard-coded into a custom environment config provider (see DeploymentConfig example below) or set in EnvironmentConfigs.json if using the DefaultEnvironmentConfigProvider.

Actions

• Remove parameters that no longer exist from wherever MetaplayClient.Initialize is called.
  • Take care to preserve and move some of the inner parameters to the appropriate level, namely ConnectionConfig and ConnectionDelegate.
• Check how your environment is set in your CI pipelines, as MetaplayDefinesPreprocessor has been deprecated.
• Migrate to using an environment config provider:
  • Create an implementation of IEnvironmentConfigProvider that provides an EnvironmentConfig (see below for compatibility with DeploymentConfig).
  • Alternatively, use the JSON-based DefaultEnvironmentConfigProvider by populating and committing EnvironmentConfigs.json (created by default in Assets/Resources/Metaplay/Editor).

DeploymentConfig Compatibility Provider Implementation

• Add a file to Assets/Code/MetaplayIntegration/DeploymentConfigToEnvironmentConfigProvider.cs.
• Adapt based on your DeploymentConfig version and customizations.
• It’s possible to move hardcoded values from the call of MetaplayClient.Initialize to DeploymentConfigToEnvironmentConfigProvider.GetCurrent.
• Other DeploymentConfig usage can be left as is.

using Metaplay.Core.Client;
using System;
using System.Collections.Generic;
using System.Linq;

public class DeploymentConfigToEnvironmentConfigProvider : IEnvironmentConfigProvider
{
    public void InitializeSingleton() { }

    public EnvironmentConfig GetCurrent()
    {
        var deploymentSpec =
            DeploymentConfig.Instance.Specs.Find(spec => spec.Id == DeploymentConfig.Instance.SelectedSpecId);
        if (deploymentSpec != null)
        {
            EnvironmentConfig environmentConfig = new EnvironmentConfig()
            {
                Id = deploymentSpec.Id,
                ConnectionEndpointConfig = new ConnectionEndpointConfig()
                {
                    ServerHost = deploymentSpec.ServerHost,
                    ServerPort = deploymentSpec.ServerPort,
                    ServerPortForWebSocket = deploymentSpec.ServerPortForWebSocket,
                    EnableTls = deploymentSpec.EnableTls,
                    BackupGateways = new List<Metaplay.Core.Client.ServerGatewaySpec>(
                        deploymentSpec.BackupGateways.Select(
                            spec => new Metaplay.Core.Client.ServerGatewaySpec(spec.Id, spec.ServerHost,
                                spec.ServerPort))),
                    CdnBaseUrl = deploymentSpec.CdnBaseUrl,
                    CommitIdCheckRule = deploymentSpec.CommitIdCheckRule,
                },
                ClientDebugConfig = new ClientDebugConfig()
                {
                    EnablePlayerConsistencyChecks = deploymentSpec.PlayerConsistencyChecks,
                    LogLevel = deploymentSpec.LogLevel,
                    LogLevelOverrides = deploymentSpec.LogLevelOverrides.Select(spec => 
                            new Metaplay.Core.Client.LogLevelOverrideSpec(spec.LogLevel, spec.ChannelName)).ToList(),
                    PlayerChecksumGranularity = ChecksumGranularity.PerActionSingleTickPerFrame,
                },
                ClientGameConfigBuildApiConfig = new ClientGameConfigBuildApiConfig()
                {
#if UNITY_EDITOR
                    AdminApiBaseUrl = deploymentSpec.AdminApiBaseUrl,
                    GameConfigPublishPolicy =
                        (Metaplay.Core.Client.GameConfigPublishPolicy)deploymentSpec.GameConfigPublishPolicy,
                    AdminApiAuthenticationTokenProvider =
                        (Metaplay.Core.Client.AuthenticationTokenProvider)deploymentSpec.AdminApiAuthenticationTokenProvider,
                    AdminApiCredentialsPath = deploymentSpec.AdminApiCredentialsPath,
                    AdminApiOAuth2Settings = new Metaplay.Core.Client.OAuth2AuthorizationServerSpec()
                    {
                        ClientId = deploymentSpec.AdminApiOAuth2Settings.ClientId,
                        AuthorizationEndpoint = deploymentSpec.AdminApiOAuth2Settings.AuthorizationEndpoint,
                        TokenEndpoint = deploymentSpec.AdminApiOAuth2Settings.TokenEndpoint,
                        Audience = deploymentSpec.AdminApiOAuth2Settings.Audience,
                        LocalCallbackUrls = new List<string>(deploymentSpec.AdminApiOAuth2Settings.LocalCallbackUrls),
                    }
#endif
                }
            };
            return environmentConfig;
        }
        else
        {
            throw new ArgumentException(
                $"DeploymentConfig with Id '{DeploymentConfig.Instance.SelectedSpecId}' could not be found!");
        }
    }
}

Default Environment Config Provider

The default environment config provider (DefaultEnvironmentConfigProvider) stores the environment configs in a JSON file, which can be edited with a text editor or with the built-in Unity editor window. The JSON file is built into separate 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.

• Edit the JSON file by hand or using the editor window found in the Metaplay/Environment Configs menu.
• (Optional) Extend EnvironmentConfig class to add custom environment-specific variables (see example in Idler: CustomExtendedEnvironmentConfig).
• (Optional) Extend DefaultEnvironmentConfigProvider to customize provider behavior (simple example: customizing file paths).
• The DefaultEnvironmentConfigProvider's active environment can be set in different ways:
  • Using the Metaplay/Environment Configs editor window
  • 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.BuildEnvironmentConfigs(string activeEnvironmentId, string[] includedEnvironmentsIds) method from your build pipeline.
  • Injecting the built files manually to the correct place.
• 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.
• 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.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.
• The automatic build by editor-set ID only happens if the built files do not yet exist. If they’ve been created by a manual BuildEnvironmentConfigs call or any other means, the automatic build will be skipped. The CI overrides will still happen and overwrite any files that exist.
• DefaultEnvironmentConfigBuilder also automatically deletes the built files in OnPostProcessBuild.