Hotfix release

Release 34.2 is the latest hotfix release for Release 34.

It contains a critical fix for WebGL, and IL2CPP builds running into an out of memory error. If you are using WebGL, please update to this release as soon as possible.

Highlights

Improved: Game Config Diffing

Game Config diffing has been revamped, the implementation is now server driven for better performance, and the UI has been rewritten for better clarity and usability.

Timeline Support for Leagues, In-Game Offers and Config-Driven Events

The LiveOps Timeline, previously introduced for LiveOps Events, is now able to show scheduled Leagues, In-Game Offers, Config-Driven Game Events, and other custom Activables that you have implemented. See Configuring Offer Groups for the Timeline and Configuring Config-Driven Events for the Timeline for more information.

Major Improvement: New CLI Functionality

The CLI has received a lot of quality of life improvements to make your life easier:

• New command to run backend integration test suites: metaplay test integration.
• New command to reset the contents of a database: metaplay database reset.
• New database snapshot commands to migrate state between environments: metaplay database export-snapshot and metaplay database import-snapshot.
• New command to get information about a game server deployment: metaplay get server-info.
• More information included in the output for: metaplay get environment-info.
• Database debugging now works without a game server deployed: metaplay debug database.
• Brush-up pass on usability on multiple commands, including the secrets management, and metaplay debug collect-cpu-profile and metaplay debug collect-heap-dump.
• The heap dump command now supports full heap dumps with dotnet-dump using: metaplay debug collect-heap-dump --mode=dump.
• Support for pre-built (to be committed to version control) LiveOps Dashboard with: metaplay build dashboard --output-prebuilt.
• Support large database queries and outputs with: metaplay debug database --from-file <query_file> --output <output_file>.
• Lots of improvements to robustness, error checks & messages, and general usability.

See the CLI releases history for a full list of changes.

Changes

Metaplay SDK

• Unity 6.2 Support: The SDK now fully supports Unity 6.2 (tested with version 6000.2.2f1). The update from earlier Unity version may require additional work in your project, see migration entry For Games Updating to Unity 6.2.

Complete List

• Added: OrderedSet<T> now implements ISet<T>.
• Added: The BigQuery schema for analytics upload is now validated upon server start.
• Added: Improved league logging for phase transitions.
• Added: Introduce IGameEngineIntegration interface to reduce Unity-specific code in the SDK core.
• Added: SecretUtil.ResolveSecretAsync(log, secretPath) now supports loading secrets from a cloud environment while running in a local development environment.
• Added: UDP listen ports now reply to special echo packets for debugging UDP connectivity. See Connectivity Validation for details.
• Added: Client authentication will now automatically differentiate ParrelSync's Unity Editor clones.
• Added: Up to 3 different credential slots can now be selected to simulate multiple players in Unity Editor.
• Added: The player's IP address is now available in PlayerActor.OnSessionStartAsync(), in sessionParams.IPAddress. Please keep in mind the relevant privacy aspects when handling this personally identifiable information.
• Added: The client is now able to connect via IPv6 also to the main hostname (the same that is used for IPv4), not only to the hostname where the first element is suffixed with -ipv6.
• Added: New runtime option ClientConnection.MaxCompressedPacketPayloadSize to control the size limit where we start failing to send network messages.
• Added: New runtime option ClientConnection.MaxDecompressedPacketPayloadSize to control the maximum size of the decompressed data received from the client.
• Added: New histogram game_player_uncompressed_size to track the player's uncompressed model size.

• Changed: Introduce (SDK-internal) #defines METAPLAY_CLIENT and METAPLAY_CLOUD and use them instead of abusing NETCOREAPP which was used for the same purpose earlier.
• Changed: The UnityLogger class has been renamed to MetaClientLogger and made more generic.
• Changed: The UnityLogHistoryTracker class has been renamed to LogHistoryTracker and made more generic.
• Changed: Network probes and incident uploading (via HTTP) now use the more general MetaHttpClient (instead of HttpWebRequest) to improve platform compatibility.
• Changed: MetaplaySDK.{StreamingAssetsPath, PersistentDataPath} are now deprecated and will be removed in the future. Use Unity's UnityEngine.Application.{streamingAssetsPath, persistentDataPath} instead.
• Changed: BotClientBase.GenerateRandomPlayerName() and other name generation methods no longer accept caller-supplied Random.
• Changed: Modernize and clean up the code for handling of maintenance mode in the client, mainly the fetching and parsing of serverStatusHint.json.
• Changed: Introduce MetaTask.MainScheduler as a generic way to access the main thread scheduler. Works outside of Unity as well. Defaults to the thread pool on platforms where there is no special main thread, e.g., on the server.
• Changed: MetaplaySDK.RunOnUnityThreadAsync() has been renamed to more general MetaplaySDK.RunOnMainThreadAsync().
• Changed: Removed ConnectionStates.Connected.LatestReceivedMessageTimestamp. For assessing network quality, Connected.IsHealthy should be used instead.
• Changed: End session on client immediately if the server node on which the Session resides is terminated.
• Changed: If session is lost due to server node shutting down, IMetaplayLifecycleDelegate.OnSessionLost() is called with an event with TechnicalErrorCode=1210 TechnicalErrorString=cluster_node_lost instead of TechnicalErrorCode=1000 TechnicalErrorString=closed_session_init_done.
• Changed: The Metaplay/Clear menu item now has been redesigned, now features a sub menu with more options.
  • Added a Clear All option to clear credentials, offline state, language, and the game config cache.
  • The Clear Credentials menu item now clears all credential slots, including Unity's Multiplayer Play Mode credentials.
• Changed: EnableCompanyAccountClientIntegrations feature flag has been removed. Browser-based login plugins for Android and iOS are now included by default.
• Changed: Deserialization in IL2CPP builds is up to 50% faster.
• Changed: ServerInitialGameConfigProvider.InitialArchiveBlob constructor no longer takes in the Archive version.
• Changed: If a Runtime Option value matches multiple environment variables, the server now refuses to boot only if the variables have different values.
• Changed: The following Metaplay.Core registries are no longer populated via reflection during runtime init: SchemaMigrationRegistry, GameConfigRepository, LiveOpsEventTypeRegistry, ModelActionRepository, IAPSharedDelegateRegistry.
• Changed: Updated Go version to 1.25.1 for entrypoint binary.
• Changed: DynamicEnum constructor no longer accepts isValid parameter and all values are considered to be valid.
• Changed: DynamicEnum value fields must now be public and readonly.
• Changed: The default value of Player.DebugConfig.ChecksumGranularity runtime option, controlling the checksumming rate of PlayerModel has been reduced. The default mode for non-local environments is now ChecksumGranularity.PerBatch, which roughly corresponds to 5 seconds worth of ticks or one action. For local environment, tick checksums are computed at most once per frame.
• Changed: CommitIdCheckRule from Environment Configs has been moved to server's Runtime Options, under ClientConnection:CommitIdCheckRule and set Disabled by default in all environments. See Commit ID Check for details.
• Changed: The Metaplay SDK unit test framework now supports isolating the integration types per test fixture using the "Integration Scopes" mechanism in source generation.
• Changed: MetaSerializerTypeScanner no longer scans through all assemblies in runtime but uses only assemblies that are part of the IntegrationAssembly set that is resolved during the build using source generation.
• Changed: MetaplayFeatureEnabledConditionAttribute used for toggling various Metaplay features no longer works on the assembly level.
• Changed: DoNotBuildForDevices Environment Config flag has been removed. Instead, device builds targeting localhost host will be disallowed by default.
• Changed: The maximum number of connections to a MySql Database, controller by DatabaseOptions.MaxConnectionsPerShard, is now automatically adjusted downwards on server startup to not exceed the maximum number of connections accepted by the database.
• Changed: Remove the legacy ability to use ID tokens for authentication during game config uploads (AdminApiUseOpenIdConnectIdToken). Access tokens are now always used.
• Changed: GameConfigBuildUtil has been renamed to BackendAdminApi, and within it, the methods PublishGameConfigArchiveToServerAsync() and PublishLocalizationArchiveToServerAsync() to UploadGameConfigArchiveToServerAsync() and UploadLocalizationArchiveToServerAsync().
• Changed: GameConfigPublishPolicy has been removed from Unity project and Environment Configs. The values are now controlled on server Runtime Options UnityEditor:Allow{GameConfig,Localization}{Upload,Publish} flags.
• Changed: Histogram metrics game_player_persisted_size and game_guild_persisted_size are now using more sensible bucket sizes.
• Changed: League option UseCustomLeagueSchedule has been changed to ScheduleType. Default value is RuntimeOptions, and Custom means the same as the old UseCustomLeagueSchedule option being true.
• Changed: The methods and getters on DefaultEnvironmentConfigProvider are now non-virtual. If you want to customize the behavior, please reach out to us so we can figure out how to best cover your use case.
• Changed: Moved Player:ModelSizeWarningThreshold to ClientConnection:PlayerModelSizeWarningThreshold.
• Changed: ClientConnection:PlayerModelSizeWarningThreshold is now initialized to 90% of ClientConnection.MaxCompressedPacketPayloadSize.
• Changed: Introduced MetaplayCoreOptions.ProjectId to separate the display name and ID from each other. See migration guide for details.
• Changed: TerminalError.ProjectNameMismatchError has been renamed to ProjectIdMismatchError, as it is now based on ProjectId and not ProjectName.

• Fixed: Fixed a few client-side culture invariance and unused variable warnings.
• Fixed: Game-server now supports DNS-based quick database failover.
• Fixed: Client now attempts to use ports of backup gateways in a random order.
• Fixed: On Android, using FileUtil.Read to read files in StreamingAssets (i.e. from inside the APK file) now works from non-Unity threads too. This makes the behavior similar to other platforms.
• Fixed: Game is now considered to be paused if application is not focused and Unity's "Run Without Focus" flag is not set, regardless if MonoBehaviour.OnApplicationPause(true) has been received or not.
• Fixed: [BigQueryAnalyticsFormat(Ignore)] attribute can now be set on a subtype of a formatted type to ignore that particular subtype in formatting.
• Fixed: PlayerModel.Language is now set for new players before experiments are evaluated.
• Fixed: The TypeScanner assembly scanning is now more accurate and no longer matches assemblies whose name starts with the name of an intentionally ignored assembly.
• Fixed: Removal of all archived Game Configs no longer timeouts if there are a large number of game configs in the database.
• Fixed: MetaDatabase.InsertAsync() now throws ItemAlreadyExistsException if item already exists, instead of MySqlException or SqliteException.
• Fixed: Fixed long, sbyte, byte, short, ushort, and uint fields not being written in BigQuery Analytics when AnalyticsSinkBigQuery.UseV2 Runtime Option was set.
• Fixed: Fix action recursion check failing for PlayerSetIsOnline if an earlier pending enqueued Server Action threw an exception.
• Fixed: [PlayerDashboardAction] attribute layoutTargetId and layoutPosition parameters now work.
• Fixed: Client Environment Configs are now identified by their Environment-ID instead of their Display Name. Specifically EnvironmentConfig.Id is now an ID.
• Fixed: Fixed debug level log spam of Removing non-existent entity watch ... (no watchSet found for source) on server shutdown.
• Fixed: Ensure that the Entity Framework Core migration history table (__EFMigrationsHistory) uses the utf8mb4_bin collation, instead of database default collation. This improves compatibility of database snapshots between MySQL and MariaDB.
• Fixed: Cleanup built environment config files if Unity client build fails, so that they don't leak into accidentally being used by the next build.
• Fixed: Fetching of a Google IAP subscription no longer logs a 404 error.
• Fixed: Code in the Metaplay Unity SDK and Unity samples now compiles with Unity 6.2. Conflicts with the new UnityEngine.EntityId type have been resolved by using a file scope type alias for Metaplay.Core.EntityId.
• Fixed: Player model league state is now handled more cleanly when importing players between environments.

LiveOps Dashboard

• Concurrent Tab Limit Removed: We've reworked the underlying communication mechanism that limited concurrent Dashboard tabs to 6-8 per browser. Dashboard now uses long-running WebSocket connections for server-sent events, which avoids exhausting the browser's concurrent connection limit.

Complete List

• Added: MModal now has a closeButtonDisabledTooltip prop to disable the modal close button and show a tooltip when hovered.
• Added: Array values that are removed by game config patches are now correctly visualized in the game config contents view.
• Added: Player Incidents can now be downloaded as JSON from the Player Incident detail pages.
• Added: A new MHorizontalDictionary component that displays key/value pairs in a horizontal grid layout.
• Added: League seasons are now visible on the LiveOps timeline.

• Changed: Major updates to Vue tooling have made the type checking of Vue components more thorough. You may see new warnings and errors in existing code.
• Changed: The MetaAbbreviateNumber component has been removed and replaced with the MAbbreviateNumber component.
• Changed: The MetaOrdinalNumber component has been removed. Use the toOrdinalString() utility function from the @metaplay/meta-utilities package instead.
• Changed: The MetaBarChart component has been removed. Use the MPlot component instead.
• Changed: DefaultDashboard/public folder is now opted-out from Git LFS storage to avoid broken images due to LFS pointer files.
• Changed: MInputDurationOrEndDateTime durationTitle and dateTimeTitle props have been removed in favor of a single label prop that accepts both a duration and an end date/time label.
• Changed: Renamed and refactored custom hint slots in MInputDurationOrEndDateTime for improved clarity and consistency.

• Fixed: The MInputSingleSelectDropdown component now correctly displays its placeholder text when no value is selected.
• Fixed: The MIconButtons danger variant now shows correctly as a muted red color when the component is disabled.
• Fixed: Fixed an issue where the "No results found" message of the MInputSingleSelectDropdown and MInputSingleSelectAsyncDropdown components was positioned too far below the input box, making it appear disconnected.
• Fixed: The MInputSingleSelectSwitch component now correctly updates its value when the modelValue prop changes.
• Fixed: The MInputSingleSelectSwitch component now behaves correctly when the disabledTooltip prop changes.
• Fixed: Changed the full dashboard info type to be correctly shown in the Player Incident detail view's raw data card.
• Fixed: Another issue where the game server metrics view would show the initial duration in minutes instead of days.
• Fixed: Fixed Dashboard failing to open if 6-8 dashboard tabs were already open.
• Fixed: Fixed session expiration banner not being displayed when credentials expired.
• Fixed: Empty or invalid StringId values are now correctly handled and rendered as empty inputs in the GeneratedUiFormConfigLibraryKeyField.
• Fixed: Fixed issue with creating new scan jobs where the name of the selected scan job was not shown correctly.
• Fixed: Improved PurchaseHistoryCard loading time for players with a high volume of in-app purchases.
• Fixed: When viewing a game config, expanding an empty library no longer shows a "JavaScript Error".
• Fixed: When viewing a player in the rare state where the player was stored in the database but not yet fully initialized, a proper "Player Not Initialized" error is now shown instead of an unexpected internal server error.
• Fixed: The MetricCard now avoids unnecessary data fetches when a user lacks permission.
• Fixed: The experiment rollout modal now shows the correct estimated duration when a schedule end time is set.
• Fixed: On the "Manage Game Config" page, when an experiment is selected, the "V" mark for variant-overridden items used to be missing if the variant's override for the item was identical to baseline. Now, a 'P' mark is displayed in this case, because all overridden items (whether or not different from baseline) can affect the resulting config when a player is involved in multiple experiments at the same time.

Documentation

• LiveOps Timeline: A new Using the LiveOps Timeline page has been added to reflect the new features added to the LiveOps Timeline on this release.
• CLI Command Reference: A reference guide to the Metaplay CLI commands is available at CLI Command Reference

Complete List

• Added: The Time and Ticks page describes how time advances in the server, the player model, and other models in general.
• Added: Connecting to Databases explains how to connect directly to the game database.
• Added: Information about how to use the new commit ID checking feature is available at Commit ID Check.
• Added: Database Operations explains the kinds of operations you can do to your game database.

• Changed: All input component code samples have been re-written in pug for improved readability and copy/pasteability.

Known Issues

There are no known issues in this release.

Migration Guide for All Customers

Please apply the following changes to your project to ensure compatibility with the latest Metaplay SDK.

Backward-Incompatible Changes

Bump your game's MetaplayCoreOptions.supportedLogicVersions to force a synchronized update of your game client and server.

Upgrade Helm Chart to Latest Version

The Metaplay SDK now requires Helm chart v0.9.0 or later for cloud deployments.

Migration Steps:

1. Update your metaplay-project.yaml to the latest Helm chart version.

   metaplay-project.yaml

   serverChartVersion: 0.x.y
   serverChartVersion: 0.9.0

2. Roll out the change to each environment by running the CI job to build and deploy a new version.

   You can do this for each environment separately, whenever is a good time for you.

Migration Guide for Self-Service Customers

Premium SDK Update Support

If your support contract includes Metaplay-provided SDK updates, all the following steps have already been applied to your project. You can skip this migration guide!

This guide offers step-by-step instructions for migrating your project to the latest version of the Metaplay SDK. You can skip the migrations steps for features you are not using in your project.

Before You Begin

It's a good idea to run the Metaplay integration test suite on your project before and after upgrading to the latest SDK version.

MyProject$ metaplay test integration

You should get a clean test run before starting the upgrade process to know that your project is in a good state, and know that any test failures after the upgrade are related to the upgrade itself.

For All Metaplay Projects

The following core SDK changes affect all Metaplay projects:

Update Project ID

A new property MetaplayCoreOptions.ProjectId was added. The ProjectId is used to uniquely identify the project in the Metaplay SDK and avoid accidentally having clients connect to the server from a different project. Previously, the MetaplayCoreOptions.ProjectName was used for this purpose, but was also used as a display name. You should set your ProjectId to be the same value as projectName used to have to avoid connection issues with your next game update!

From now on, MetaplayCoreOptions.ProjectName is used for display purposes only, mainly on the LiveOps Dashboard. You may freely give it any value you like.

Migration Steps:

1. Update your initialization of MetaplayCoreOptions to include projectId. Use the same value as projectName used to have!

   GlobalOptions.cs

   public MetaplayCoreOptions Options { get; } = new MetaplayCoreOptions(
       // ... Old comment no longer applies...
       projectName:            "MyProjectId",               
       // Unique project ID. DO NOT CHANGE!
       projectId:              "MyProjectId",               
       // Display name of project. You can now change this.
       projectName:            "MyProjectId",               
       ...
   );

The following LiveOps Dashboard changes affect all Metaplay projects:

Renormalize Assets to Apply Git LFS Changes

The MetaplaySDK/Frontend/DefaultDashboard/public is now opted-out from Git LFS (Large File Storage) to avoid the folder contents becoming LFS pointer files when pulled with the default git settings, as is common in CI systems.

Git LFS does not detect these changes automatically. If the files are tracked by Git LFS, the files need to be manually normalized to ensure LFS detects the change, and avoids converting them to the pointer files.

Migration Steps:

1. Run git add --renormalize MetaplaySDK/Frontend/DefaultDashboard/public/

For Games Updating to Unity 6.2

The following changes affect projects updating to Unity 6.2:

Updating to Unity 6.2

Unity 6.2 introduces type EntityId in the UnityEngine namespace in the Unity core assembly. This new type will conflict with the existing Metaplay SDK type Metaplay.Core.EntityId in any source files that have using statements both for UnityEngine and Metaplay.Core and that refers to the type EntityId without further namespace qualification, as the compiler will not be able to deduce which type is meant.

The options for resolving the ambiguous reference are:

1. Update references to the type to be fully qualified, i.e. change EntityId to Metaplay.Core.EntityId in source code files that are using both namespaces.

2. Add a file scope type alias for Metaplay.Core.EntityId in source code files that are using both namespaces. This option will not work if your code is also referring to UnityEngine.EntityId, in that case you will have to choose option 1 or invent another name for the type alias of one of the EntityId types.

   using Metaplay.Core; // Metaplay.Core.EntityId
   using UnityEngine; // UnityEngine.EntityId
   using EntityId = Metaplay.Core.EntityId; 

For Games With Customized LiveOps Dashboard

The following LiveOps Dashboard changes affect projects that have a game-specific dashboard project:

Update the LiveOps Dashboard Project Files

As usual, we have updated the underlying dependencies and configurations of the LiveOps Dashboard. This causes changes to several configuration files, which you will need to update in your dashboard project. We use the MetaplaySDK/Frontend/DefaultDashboard folder as the source of truth for these files.

Migration Steps:

1. Update the package.json to update your project's dependencies.

   • If you have custom dependencies, manually update them or use a file comparison tool to merge the changes.
   • If not, copy and overwrite the package.json file directly from the MetaplaySDK/Frontend/DefaultDashboard directory. Next, restore the name property inside the file to that of your project. This is typically of the form "name": "<projectName>-dashboard".

2. Copy and overwrite the following files:

   • vite.config.ts
   • .gitattributes

Clear and Recreate the Dashboard Dependencies

To ensure that your dashboard project has the correct dependencies, you will need to clear the existing cached files and recreate them.

You should ensure that you have Node version 22.14.0 (the latest 22.x version at the time of writing) installed. To check the current version, run node --version. If you are using nvm, you can update Node with:

# Install Node 22.14.0 with Node Version Manager (nvm).
nvm install 22.14.0

# Use the new version.
nvm use 22.14.0

Migration Steps:

1. Next, remove any files that Node has cached in your repository. This will lead to a fresh install of all dependencies.
   • Run git clean -fdx ':(glob)**/node_modules/*' from the root of your repository. This clears any currently installed dependencies.
   • Run git clean -fdx ':(glob)**/dist/*' from the root of your repository. This clears any previously built files.
   • Delete the pnpm-lock.yaml file from the root of your repository. This clears the cached dependency versions.
2. Run pnpm install in your 'Dashboard' folder. This recreates all of the above files and folders with the correct dependencies.

Renormalize Assets to Apply Git LFS Changes

The Dashboard/public is now opted-out from Git LFS (Large File Storage) to avoid the folder contents becoming LFS pointer files when pulled with the default git settings, as is common in CI systems.

If your custom public folder is currently tracked by Git LFS, the files need to be manually normalized to ensure LFS detects the change and avoids converting them to pointer files.

Migration Steps:

1. Navigate to the Backend directory of your project.
2. Run git add --renormalize Dashboard/public/

For Games With Custom LiveOps Dashboard Components

As a part of continued code review and polish of the dashboard codebase, we have done a few breaking changes to internal APIs that you may be using in your custom components.

Migrate MetaAbbreviateNumber to MAbbreviateNumber

• The MetaAbbreviateNumber component has been removed and replaced with the MAbbreviateNumber component.

Migration Steps:

1. Find all instances of the MetaAbbreviateNumber component and meta-abbreviate-number in your dashboard project.

2. Import the new MAbbreviateNumber component from the @metaplay/meta-ui-next.

   import { MAbbreviateNumber } from '@metaplay/meta-ui-next'

3. Replace all instances of MetaAbbreviateNumber and meta-abbreviate-number with MAbbreviateNumber in your code.

   meta-abbreviate-number(:value="1234567890")
   MAbbreviateNumber(:number="1234567890")

Migrate MetaOrdinalNumber to toOrdinalString()

The MetaOrdinalNumber component has been removed in favor of the toOrdinalString() utility function from the @metaplay/meta-utilities package.

Migration Steps:

1. Find all instances of the MetaOrdinalNumber component and meta-ordinal-number in your dashboard project.

2. Import the toOrdinalString utility function from the @metaplay/meta-utilities package.

   import { toOrdinalString } from '@metaplay/meta-utilities'

3. Replace the MetaOrdinalNumber and meta-ordinal-number with the toOrdinalString() function:

   meta-ordinal-number(:value="1")
   span {{ toOrdinalString(1) }} 

Migrate MInputDurationOrEndDateTime Props and Slots

The MInputDurationOrEndDateTime durationTitle and dateTimeTitle props have been removed and replaced by a single label prop. The new label prop requires both duration and endDateTime labels to be provided.

Migration Steps:

1. Find all instances of MInputDurationOrEndDateTime in your project that include the label, durationTitle and/or dateTimeTitle props.
2. Update the label prop as follows:

MInputDurationOrEndDateTime(
    :model-value="duration"
    :update:model-value="duration"
    label="Example Duration"
    duration-title="Example Duration"
    dateTime-title="Example End Date Time"
    :label="{ duration: 'Example Duration', endDateTime: 'Example End Date Time' }"
    ...
    )

The duration-hint-message slot has been renamed to duration-input-hint. The end-time-hint-message slot has been renamed to end-time-input-hint. The dateTime slot prop has been renamed to projectedEndDate. The duration slot prop has been renamed to projectedDuration.

Migration Steps:

1. Find all instances of the MInputDurationOrEndDateTime component in your project that include the duration-hint-message and/or end-time-hint-message slots.
2. Replace as follows:

MInputDurationOrEndDateTime(
    :model-value="duration"
    :update:model-value="duration"
    )
    template(#duration-hint-message="durationHintProps") This example will expire on {{ durationHintProps.dateTime }}. 
    template(#end-time-hint-message="endTimeHintProps") This example is valid until {{ endTimeHintProps.duration }}. 
    template(#duration-input-hint="{ projectedEndDate }") This example will expire on {{ projectedEndDate }}. 
    template(#end-time-input-hint="{ projectedDuration }") This example is valid until {{ projectedDuration }}. 

For Games Inheriting DefaultEnvironmentConfigProvider

The methods and getters on DefaultEnvironmentConfigProvider are now non-virtual. The behavior of the class is so complicated that wholesale exposing of the internals is quite risky as inheriting code could easily break it in unexpected ways. If you want to customize the behavior, please reach out to us and describe your use case and we'll help you find a safe way to do so.

As a hot-fix, you can add the necessary virtuals back to the getters or methods that you need to be virtual. This way, you can proceed with upgrading Metaplay SDK while we work on a more permanent solution.

Miscellaneous API Changes

These changes affect you in case you happen to use any of the APIs changed. You can build your project to get a list of any incompatibilities instead of going through the list one item at a time.

Update Calls to BotClientBase.GenerateRandomPlayerName() and Other Name Generation Methods.

To simplify BotClientBase.GenerateRandomPlayerName(), GenerateRandomGuildName(), and GenerateRandomGuildDescription(), they no longer take Random parameter.

Migration Steps:

1. Remove Random parameter from call-sites:

   string playerName = GenerateRandomPlayerName(new Random()); 
   string playerName = GenerateRandomPlayerName(); 
   
   string guildDisplayName = GenerateRandomGuildName(random); 
   string guildDescription = GenerateRandomGuildDescription(random); 
   string guildDisplayName = GenerateRandomGuildName(); 
   string guildDescription = GenerateRandomGuildDescription(); 

2. If BotClient overrides the default implementations, update the signatures:

   protected override string GenerateRandomPlayerName(Random random) 
   protected override string GenerateRandomPlayerName() 
   {
   }
   
   protected override string GenerateRandomGuildName(Random random) 
   protected override string GenerateRandomGuildName() 
   {
   }
   
   protected override string GenerateRandomGuildDescription(Random random) 
   protected override string GenerateRandomGuildDescription() 
   {
   }

Remove EnableCompanyAccountClientIntegrations Feature Flag.

The feature flag for EnableCompanyAccountClientIntegrations has been removed and the login dependencies are now included in SDK by default.

Migration Steps:

1. Remove feature flag from MetaplayCoreOptions:

   public class GlobalOptions : IMetaplayCoreOptionsProvider
   {
       public MetaplayCoreOptions Options { get; } = new MetaplayCoreOptions(
           ...
           featureFlags: new MetaplayFeatureFlags
           {
               ...
               EnableCompanyAccountClientIntegrations = true
           });
   }

2. Remove io.metaplay.unitysdk.androidcustomtabs package from Unity:

   UnityProjectDirectory/Packages/manifest.json

   {
       "dependencies": {
           ...
           "io.metaplay.unitysdk.androidcustomtabs": "...", 
       }
   }

Update Calls to InitialArchiveBlob Constructor.

ServerInitialGameConfigProvider.InitialArchiveBlob constructor no longer accepts the archive version. The version is deduced from the archive bytes.

Migration Steps:

1. Remove argument from new InitialArchiveBlob call sites:

   new InitialArchiveBlob(
       archiveVersion, 
       archiveBytes,
       dataSource
       ...
       );

Update GameConfigEntryInfo Property Accesses.

GameConfigEntryInfo's properties have been rearranged to avoid confusion and also due to changes in how the data is populated.

• To avoid confusion between the name of a config entry stored in the config archive (its "entry name") and its C# member name, GameConfigEntryInfo's Name property has been renamed to the more explicit EntryName.
• MemberInfo is no longer readily available, but most of the useful information is now available directly, in members Type, DeclaringType, MemberName, GetEntry(), and SetEntry(). If you still need MemberInfo to access some other information, you can get it using ResolveMemberInfo(), but be aware that it involves reflection and can have significant cost if used a lot.

Migration Steps:

1. If you get an obsoleted error about GameConfigEntryInfo.Name, access EntryName instead.

   GameConfigEntryInfo entryInfo = ...;
   string entryName = entryInfo.Name; // error CS0619: 'GameConfigEntryInfo.Name' is obsolete
   string entryName = entryInfo.EntryName; 

2. If you get an obsoleted error about GameConfigEntryInfo.MemberInfo, instead access one of the other properties depending on what information you need, or call ResolveMemberInfo().

   GameConfigEntryInfo entryInfo = ...;
   // Member name is now directly available.
   string memberName = entryInfo.MemberInfo.Name; 
   string memberName = entryInfo.MemberName; 
   // Less common data, like attributes, still need to come from the MemberInfo.
   MyConfigAttribute attribute = entryInfo.MemberInfo.GetCustomAttribute<MyConfigAttribute>(); 
   MyConfigAttribute attribute = entryInfo.ResolveMemberInfo().GetCustomAttribute<MyConfigAttribute>(); 

Remove isValid Argument from DynamicEnum Constructors.

Creation of DynamicEnums that are Invalid or Hidden are no longer supported. All enum values are now valid, and it is no longer necessary to mark the values as valid.

Migration Steps:

1. For each class inheriting DynamicEnum, remove isValid argument from constructor.

   public class ExampleDynamicEnum : DynamicEnum<ExampleDynamicEnum>
   {
       public static readonly ExampleDynamicEnum Value0 = new ExampleDynamicEnum(0, "TestValue0");
       public static readonly ExampleDynamicEnum Value1 = new ExampleDynamicEnum(1, "TestValue1");
   
       protected ExampleDynamicEnum(int id, string name) : base(id, name, isValid: true)
       protected ExampleDynamicEnum(int id, string name) : base(id, name)
       {
       }
   }

Make DynamicEnum Value Fields readonly.

Value fields in a DynamicEnum are now required to be public, static and readonly. If a static field is found that is not public or readonly, compilation will fail.

Migration Steps:

1. Fix field declarations with compilation errors:

   public class MyDynamicEnum : DynamicEnum<MyDynamicEnum>
   {
       static readonly MyDynamicEnum Value1 = new MyDynamicEnum(1, nameof(Value1)); // error MP_DEA_002: Invalid DynamicEnum field declaration
       public static readonly MyDynamicEnum Value1 = new MyDynamicEnum(1, nameof(Value1)); 
   
       public static MyDynamicEnum Value2 = new MyDynamicEnum(2, nameof(Value2)); // error MP_DEA_002: Invalid DynamicEnum field declaration
       public static readonly MyDynamicEnum Value2 = new MyDynamicEnum(2, nameof(Value2)); 
   
       public MyDynamicEnum(int id, string name) { ... }
   }

2. If a field is not intended to be an enum value, annotate it with [IgnoreDataMember] attribute:

   public class MyDynamicEnum : DynamicEnum<MyDynamicEnum>
   {
       [IgnoreDataMember] 
       MyDynamicEnum _alternativeValue;
   
       public MyDynamicEnum(int id, string name) { ... }
   }

Migrate Customized CommitIdCheckRule into Runtime Options.

CommitIdCheckRule has been removed from Client's Environment Configs and moved into server-side Runtime Options. If you have customized the rule, you must port the customizations to the Runtime Options.

The default value of CommitIdCheckRule is now Disabled on all environments. Note that in some development environments, CommitIdCheckRule defaulted to OnlyIfDefined. If you want to keep this value, you need to migrate the value manually. For more information on CommitIdCheckRule, see Commit ID Check.

Migration Steps:

1. For each environment that has a customized rule, apply the rule to the environment's runtime options:
   Backend/Server/Config/Options.<env>.yaml

   ClientConnection:
       # For CommitIdCheckRule.Disabled
       CommitIdCheckRule: Disabled
   
       # For CommitIdCheckRule.OnlyIfDefined
       CommitIdCheckRule: OnlyIfDefined
   
       # For CommitIdCheckRule.Strict
       CommitIdCheckRule: Strict

Migrate Customized GameConfigPublishPolicy into Runtime Options.

GameConfigPublishPolicy has been removed from Client's Environment Configs and moved into server-side Runtime Options. If you have customized the policy values, you must port the customizations to the Runtime Options.

The default values remain the same:

• Uploading and publishing to local server is allowed without prompting for confirmation.
• Uploading and publishing to development environments is allowed if user has been prompted to confirm the target environment.
• Uploading is allowed to staging and production environments, but publishing is not. Game config must be made active in LiveOps Dashboard.

If Unity requires knowing whether it is allowed to publish, the policy can be fetched using the BackendAdminApi.FetchPublishPolicyAsync() API.

Migration Steps:

1. For each environment that has a customized policy, apply the policy to the environment's runtime options:
   Backend/Server/Config/Options.<env>.yaml

   UnityEditor:
       # For GameConfigPublishPolicy.NotAllowed
       AllowGameConfigUpload: false
       AllowLocalizationUpload: false
   
       # For GameConfigPublishPolicy.UploadOnly
       AllowGameConfigUpload: true
       AllowGameConfigPublish: false
       AllowLocalizationUpload: true
       AllowLocalizationPublish: false
   
       # For GameConfigPublishPolicy.AskForConfirmation
       AllowGameConfigUpload: true
       AllowGameConfigPublish: true
       GameConfigPublishPrompt: "Are you sure you want to publish game config into <env>?"
       AllowLocalizationUpload: true
       AllowLocalizationPublish: true
       LocalizationPublishPrompt: "Are you sure you want to publish game config into <env>?"
   
       # For GameConfigPublishPolicy.Allowed
       AllowGameConfigUpload: true
       AllowGameConfigPublish: true
       GameConfigPublishPrompt: ""
       AllowLocalizationUpload: true
       AllowLocalizationPublish: true
       LocalizationPublishPrompt: ""

Rename References to GameConfigBuildUtil into BackendAdminApi.

GameConfigBuildUtil has been renamed to BackendAdminApi in order to match the actual contents of the helper. BackendAdminApi provides API binding for the Backend Server's HTTP AdminAPI.

Additionally, the functions for publishing game configs and localizations have been changed. The confirmDialog boolean has been removed altogether, as the policy of requiring confirmation is now declared in server options (see the above migration note for GameConfigPublishPolicy).

Migration Steps:

1. Update references from GameConfigBuildUtil into BackendAdminApi:

   ... = await GameConfigBuildUtil.DownloadGameConfigAsync(...); 
   ... = await BackendAdminApi.DownloadGameConfigAsync(...); 

2. Update calls to PublishGameConfigArchiveToServerAsync() to use UploadGameConfigArchiveToServerAsync() instead:

   await GameConfigBuildUtil.PublishGameConfigArchiveToServerAsync( 
   await BackendAdminApi.UploadGameConfigArchiveToServerAsync( 
       adminApiBaseUrl,
       configArchive,
       authorizationToken,
       confirmDialog, 
       setAsActive, 
       name, 
       description 
       new BackendAdminApi.GameConfigUploadOptions() 
       { 
           Name = name, 
           Description = description, 
           SetAsActive = setAsActive, 
       } 
       );

3. Update calls to PublishLocalizationArchiveToServerAsync() to use UploadLocalizationArchiveToServerAsync() instead:

   await GameConfigBuildUtil.PublishLocalizationArchiveToServerAsync( 
   await BackendAdminApi.UploadLocalizationArchiveToServerAsync( 
       adminApiBaseUrl,
       configArchive,
       authorizationToken,
       confirmDialog, 
       name, 
       description 
       new BackendAdminApi.LocalizationUploadOptions() 
       { 
           Name = name, 
           Description = description, 
           SetAsActive = true
       } 
       );

Change UseCustomLeagueSchedule: true RuntimeOption to ScheduleType: Custom.

If any of the league runtime options defines UseCustomLeagueSchedule: true, it should be changed to ScheduleType: Custom.

Migration Steps:

1. Change UseCustomLeagueSchedule: true to ScheduleType: Custom in Options.base.yaml:

   MyLeague:
     UseCustomLeagueSchedule: true
     ScheduleType: Custom

Update usages of Player:ModelSizeWarningThreshold to ClientConnection:PlayerModelSizeWarningThreshold

Player:ModelSizeWarningThreshold has been moved to ClientConnection:PlayerModelSizeWarningThreshold and is now initialized to be 90% of ClientConnection.MaxCompressedPacketPayloadSize.

Migration Steps:

1. Update runtime option usages of Player:ModelSizeWarningThreshold

   Player: 
       ModelSizeWarningThreshold: ...
   ClientConnection: 
       PlayerModelSizeWarningThreshold: ...

2. Update C# usages of PlayerOptions.ModelSizeWarningThreshold

   RuntimeOptionsRegistry.Instance.GetCurrent<PlayerOptions>().ModelSizeWarningThreshold; 
   RuntimeOptionsRegistry.Instance.GetCurrent<ClientConnectionOptions>().PlayerModelSizeWarningThreshold; 

Update Uses of ProjectNameMismatchError to ProjectIdMismatchError

TerminalError.ProjectNameMismatchError has been renamed to ProjectIdMismatchError, because the detection is now based on ProjectId (in MetaplayCoreOptions) instead of ProjectName. If you have custom network error handling that refers to this error, it needs to be updated.

Migration Steps:

1. Update ProjectNameMismatchError references to ProjectIdMismatchError.
2. Update ClientProjectName and ServerProjectName member references to ClientProjectId and ServerProjectId.
3. Update MetaplayClientConnectionErrors.ProjectNameMismatch references to MetaplayClientConnectionErrors.ProjectIdMismatch.

Final Validation

You should run the Metaplay integration test suite on your project after the SDK upgrade to make sure everything is still working as expected:

MyProject$ metaplay test integration

Release 34.1

Released on: September 18th, 2025

Changes

• Critical fix: Fix bug in file storage paths for persistent data on WebGL introduced in R34.0. This bug causes any read of StreamingAssets resources to fail on WebGL. Most notably, accessing the builtin localization files fails, which prevents session start when the remembered initial language doesn't match the language stored in the player model.
• Fixed: Improved performance of LiveOps timeline.
• Fixed: Include missing ProjectId in telemetry.
• Fixed: On WebGL, fixed FileUtil.ReadAllBytesAsync() returning null instead of throwing the expected IOException when accessing a missing file on the persisted IndexedDB filesystem.

Release 34.2

Released on: October 24th, 2025

Changes

• Changed: Update Akka and Kubernetes to non-vulnerable versions.

• Fixed: Fixed OOM failure in Unity IL2CPP release builds when SharedGameConfig or ServerGameConfig contained hundreds of libraries.

• Fixed: Fixed the DailyCohortChart component showing empty data even when there was non-empty data.