Metaplay Docs

Appearance

Release 37

May 28th, 2026

Highlights ​

  • Major Improvement: Runtime Options View

The Runtime Options view has been rewritten to provide smoother navigation with integrated search. This makes it easier to debug your runtime options settings from the dashboard.

  • Major Improvement: Raw Data View

The Raw Data views have been rewritten to provide smoother navigation with integrated search. This makes it easier to navigate, understand and debug your raw data.

  • New Feature: Unity In-App Purchasing v5 Support

You can now build your project against Unity's com.unity.purchasing 5.x package. The SDK auto-detects the installed version and selects the matching codepath, so existing v4 projects continue to work unchanged. v5 validates Apple receipts via StoreKit 2 / JWS. See Upgrading to Unity IAP v5 when you are ready to migrate.

Changes ​

Metaplay SDK ​

  • .NET 9 Support Removed - The minimum .NET runtime version for the backend is .NET 10. If you haven't upgraded yet, follow the Release 36 migration guide For All Metaplay Projects.

  • Prebuilt Code Analyzers - The Metaplay code analyzers (Metaplay.CodeAnalyzers and Metaplay.CodeAnalyzers.Shared) are now shipped as prebuilt DLLs instead of project references. This eliminates sporadic file-locking build failures when building multiple projects in parallel.

  • New Analyzer: Incorrect StringId.Value Checks - A new code analyzer (MP_SID_00, MP_SID_01) warns when code incorrectly checks StringId.Value for null or emptiness. A no-value StringId is represented by the reference itself being null, so .Value is never null or empty — these checks are bugs that should test the StringId reference instead.

  • Stricter Database Writes with MySql Backend - Game servers using the MySql backend now enforce strict per-session validation on every database write, regardless of the server's global configuration. Writes that would previously have been silently truncated, coerced, or accepted with invalid values — overlong strings, out-of-range numerics, zero dates — now raise errors at write time. This particularly affects cloud deployments on AWS Aurora MySQL, which historically shipped with permissive defaults. Only relevant if your project defines custom database tables or columns. See the migration guide for what to watch for and how to temporarily opt out.

  • Major Improvement: GameConfig Build Window - The Unity editor window for building and deploying game configs has been redesigned with improved visual layout, build feedback, and reliable cancellation. You can now cancel builds mid-operation, and a new progress system shows per-entry detail during builds. See the migration guide for one breaking API change.

    The redesigned GameConfig Build Window showing build parameters, incremental build options, build results with validation report, and deploy section.

Complete List
  • Added: GameConfigBuildUtil — new engine-agnostic build utility class that can be used to trigger builds programmatically.
  • Added: UnityGameConfigBuildHelper — Unity-specific build helper with a public API for triggering builds from code, scripts, or AI assistants. Call UnityGameConfigBuildHelper.Build() from any editor context.
  • Added: GameConfigBuildProgress class and GameConfigBuildDebugOptions.Progress for structured per-entry build progress reporting.
  • Added: IGameConfigSourceFetcherProvider.Progress — default interface property for granular progress reporting during source fetching.
  • Added: FileUtil.ReadAllBytesAsync(string, CancellationToken) overload for cancellable file reads.
  • Added: F32 and F64 types are now editable via the Unity Inspector.
  • Added: Unity In-App Purchasing v5 is now supported. Existing Unity Purchasing v4 projects continue to work unchanged. See Upgrading to Unity IAP v5 for the migration steps.
  • Added: BotClientMain now detects at startup if Metaplay.Server is accidentally referenced and fails early with a clear error message.
  • Added: PlayerEventClientConnected analytics event now contains the Id of the active Game Config.
  • Added: Localization sheet structure is now more flexible and consistent with other game config parsing: comment rows and columns, as well as fully-empty rows and columns, are allowed at any position, and columns can be ordered freely (TranslationId doesn't have to be first).
  • Added: Localization sheet parsing errors have been improved to point out the actual cell location in the source data.
  • Added: Server log entries from Connection entities now contain also the Player entity ID after the login has been validated. This makes it easier to search for a given player's connections in the log.
  • Added: MetaDuration properties on Runtime Options classes can now be configured from YAML, command line, and environment variable sources using the unit format (e.g. 1d 2h 30m, 30m, 1.5s). See Supported Value Types for details.
  • Added: LocalServer.CommandLineArgumentProvider integration class allows customizing command line for the Local Server started from Unity.
  • Added: GameConfigDataContent<TConfigData> can now be used also for abstract game config base types, not just concrete types.
  • Added: IGameConfigData classes without parameterless constructors are now allowed. The need for a parameterless constructor can be avoided by using the [MetaDeserializationConstructor] and [MetaGameConfigBuildConstructor] attributes.
  • Added: EntityActor.CreateWakelock() to allow temporarily extending entity lifetime.
  • Added: New override GuildActor.OnMemberIsOnlineChangedAsync() for reacting to guild member coming online or going offline.
  • Added: New Database:MySqlSqlMode runtime option to configure the per-session MySQL sql_mode. Defaults to the upstream MySQL 8.0 strict default; set to null to inherit the database server's global sql_mode.
  • Added: Overriding GuildSearchActorBase.GetSearchFilter() allows narrowing guild search results at the SQL level.
  • Added: ICustomComparable interface for using game-defined value types (such as named tiers or composite ranks) as range-comparable player segment properties. Implement the interface on your type and register a parser to make it usable in the segment sheet's PropMin/PropMax columns. See Custom Comparable Properties for details.
  • Changed: IGameConfigSourceData.Get() now takes a CancellationToken parameter. The old Get() is preserved as an [Obsolete] default interface method that forwards to the new one. If you have custom IGameConfigSourceData implementations, update them to accept the token. See the migration guide.
  • Changed: Server-side session retention is now configured with the SessionOptions.SessionLingerDuration runtime option. ConnectionConfig.MaxSessionRetainingPauseDuration and ConnectionConfig.MaxNonErrorMaskingPauseDuration are removed, and SessionActor.ShutdownPolicy is sealed.
  • Changed: ConnectionConfig.SessionResumptionAttemptMaxDuration has been replaced by ConnectionConfig.MaxReconnectingForegroundDuration. The new budget counts foreground time only, so a brief background interruption no longer eats the session-resumption attempt window.
  • Changed: MetaplaySDK.ApplicationPauseMaxDuration property has been removed.
  • Changed: GuildSearchActorBase.EntityIdOnCurrentNode has been replaced by the GuildSearchActorBase.GetLocalNodeEntityId() helper.
  • Changed: DefaultEnvironmentConfigProvider.GetAllEnvironmentConfigs() now returns IReadOnlyList<EnvironmentConfig> instead of EnvironmentConfig[], avoiding an unnecessary array copy on each call. Callers using .Length should switch to .Count.
  • Changed: The editor environment selection now defaults to the first configured environment instead of "no environment selected" when no explicit selection has been made.
  • Changed: Desync reports now show the dictionary key by name or value for int- and enum-keyed dictionaries, instead of a positional index. This makes it easier to identify which entry differs.
  • Changed: ParseLegacyVersion1PoolPage() has been removed from PersistedGuildDiscoveryPool.
  • Changed: Bumped Microsoft.CodeAnalysis packages in Metaplay.Cloud from 4.8.0 to 4.14.0, fixing locale warnings in CI and resolving a CVE in a transitive dependency (Microsoft.Build.Tasks.Core).
  • Changed: Compression libraries migrated from IronCompress to pure managed .NET alternatives: Zstandard now uses ZstdSharp and LZ4 now uses K4os.Compression.LZ4. This removes the now-archived IronCompress dependency and its bundled native binaries entirely.
  • Changed: Replaced the SharpCompress dependency in Metaplay.Cloud with the built-in System.Formats.Tar API. This resolves SCA scanner reports for CVE-2026-44788; the SDK was not exploitable, as the only use site is a memory-only read of a trusted MaxMind archive.
  • Changed: Bumped Parquet.Net in Metaplay.ServerShared from 4.25.0 to 5.6.1 to drop the vulnerable transitive Snappier 1.1.6 dependency (GHSA-pggp-6c3x-2xmx). Internal Parquet snapshot reading in the player re-delete admin endpoint has been migrated to the new ParquetSerializer API.
  • Changed: MetaFormUseAsContextAttribute is renamed to MetaFormUseAsRootAttribute.
  • Changed: The legacy Scripts/integration-tests.py script has been removed. Use metaplay test integration instead.
  • Changed: Code analyzers are now shipped as prebuilt DLLs and referenced via a shared Metaplay.Analyzers.targets file, eliminating file-locking errors during parallel builds. See the migration guide for upgrade instructions.
  • Changed: Server web API middleware (such as the developer exception page and HSTS) now uses Metaplay's own EnvironmentFamily configuration instead of the ASP.NET hosting environment to determine the active deployment. The launchSettings.json file is no longer needed.
  • Changed: Server web APIs now enforce HTTPS in all cloud environments by sending an HSTS header with a 1 year max age.
  • Changed: The server now displays a clear error message with instructions when database schema changes are detected but no migration has been created. Previously, this scenario produced an opaque EF Core exception.
  • Changed: Replace new Random() with Random.Shared throughout the server-side codebase.
  • Changed: byte[] arrays are now JSON-serialized as a base64-encoded string in all serialization modes. Specifically they are NOT encoded as {"$type":"System.Byte[]","$value":"XXX"}.
  • Changed: Client now automatically reconnects if failing to run a server-enqueued action within the time limit. Incident report is generated as previously.
  • Changed: Action and analytics event collection members now use IReadOnlyList<T> instead of List<T> to express immutability.
  • Changed: DisconnectedFromServer is now emitted also if session start fails, to better mirror ConnectedToServer behavior.
  • Changed: ChecksumUtil.PrintDifference has been removed as it was a complicated wrapper for PrettyPrinter.Difference().
  • Changed: BeginSubscribeToAssociatedEntityAsync() no longer takes clientChannelId parameter. Generate ID with NextEntityChannelId() instead.
  • Changed: BigQuery analytics sink now supports empty (no fields) subtypes for types used in analytics events. In the analytics data, these types will have the $t synthetic type field.
  • Changed: JWKSPublicKeyCache minimum renewal period increased from 10s to 60s to reduce unnecessary key refresh requests.
  • Changed: All service entities are started regardless if overridden EntityShard.StartAsync() calls the base.StartAsync() or not.
  • Changed: Updated entrypoint binary to use Go v1.26.3.
  • Changed: MetaplayWebhookController is deprecated to encourage use of PublicWebApiController. MetaplayWebhookController will continue to be supported.
  • Changed: When a client login attempt uses guest credentials with the wrong AuthToken, a warning-level message is logged on the server, not only debug-level.
  • Changed: Setting server option AppleStore:AppleSharedSecret directly is now deprecated. This is in favor of the new AppleStore:AppleSharedSecretPath which allows using secrets management to avoid storing secrets in the project repository.
  • Changed: Removed Fast-forwarded model log debug message as it was not useful.
  • Changed: Files written with ConfigArchiveBuildUtility.FolderEncoding.WriteToDirectory() now have a binary header, changing the on-disk format. To access a single entry without reading the whole directory, use FolderEncoding.ReadEntryContents[Async]().
  • Changed: Built localization files now have a binary header to prevent version control mutating them as if they were text.
  • Changed: ConfigArchiveBuildUtility.FolderEncoding.WriteToDirectory(archive, path) is deprecated, use WriteToDirectory(archive, path, mode) instead.
  • Changed: guildInviteCodeSalt in MetaplayCoreOptions is now an optional parameter.
  • Changed: GuildActor.ShouldAcceptPlayerJoin() signature is changed to receive ShouldAcceptPlayerJoinArgs.
  • Changed: PlayerIncidentStorage.SerializeAndPersistIncidentAsync() has been renamed to TrySerializeAndPersistIncidentAsync() and it returns whether the incident was both new and not invalid.
  • Changed: PersistedAuditLogEvent constructor now truncates EventId, Source, Target, and SourceIpAddress explicitly in application code to fit their declared column lengths. Previously this truncation happened silently in the database under permissive sql_mode; doing it in code keeps behavior consistent under strict sql_mode.
  • Changed: EF Core database tables no longer default integral primary keys to auto-incrementing.
  • Changed: EF Core database tables with auto-incrementing columns are now explicitly disallowed.
  • Changed: Default column type for string is now LONGTEXT instead of TEXT. TEXT was limited to at most 64k characters on MySQL backend.
  • Changed: Default column type for long is now BIGINT instead of INTEGER. INTEGER was limited to at most 32-bit integer range on MySQL backend.
  • Changed: EF Core table columns of type uint or ulong are no longer supported implicitly. The column type must be explicitly set with the [Column] attribute.
  • Fixed: Client TLS handshakes now punycode the domain name as expected and no longer pass a trailing dot to SNI.
  • Fixed: Client DNS lookups now punycode the hostname and add a trailing dot to force FQDN resolution.
  • Fixed: Fixed a rare SQL unique constraint error during bot client login.
  • Fixed: BigQueryFieldValidator.VerifyField now includes the full dotted path to the failing field in validation error messages, making it easier to identify nested schema mismatches.
  • Fixed: Entity kinds with ShardingStrategies.CreateSingletonService() no longer allow on-demand creation of entities other than the singleton.
  • Fixed: WebSocket connections could fail with ProtocolErrorUnexpectedLoginMessage during session start if the server produced game messages before the session start response was fully delivered to the client.
  • Fixed: Dockerfile.server heredoc blocks now strip \r characters, making the build resilient to CRLF line endings (e.g., when the project is managed outside of Git without .gitattributes enforcement).
  • Fixed: Incident statistics could incorrectly exclude recently uploaded incidents from clients with clocks set behind - now filters by server-side PersistedAt timestamp instead of client-provided IncidentId.
  • Fixed: Fixed64.Lerp(a, b, t) now correctly returns a when t=0 and b when t=1, matching the standard lerp convention. Previously the interpolation was reversed.
  • Fixed: Fixed BrowserSDK using wrong key in login tokens cache lookup, causing needless fallbacks to localstorage.
  • Fixed: Client failing to run a server-enqueued action within the time limit no longer causes server error to be logged. This caused spurious errors from clients with poor connectivity. The message is now logged on the warning level.
  • Fixed: Socket errno to error message mapping now works on iOS too, converting internal errors like mono-io-layer-error (61) into readable connection refused messages.
  • Fixed: Some network errors during application pause were not classified as SessionLostInBackground transient errors.
  • Fixed: Fixed session start failure not preventing running the game logic, causing unnecessary warnings.
  • Fixed: Fixed a single session start failure resulting in two Incident Reports, one SessionStartFailure as expected but also one copy as a TerminalNetworkError.
  • Fixed: When the client-side in-app purchasing store UI flow took long enough that the backgrounded game session was lost and a new session was started, the purchase validation could become stuck until the client application was restarted. This was observed at least on Android devices. This has been fixed so that the purchase validation continues when the new session is started, without needing to restart the client application.
  • Fixed: Incident reporting during session start reported some connection failures as TerminalNetworkErrors instead of SessionStartFailed.
  • Fixed: JournalModelCloningChecker has been removed as it was unsound and could have produced false warnings and exceptions when [NoChecksum] fields were present.
  • Fixed: METAPLAY_CREDENTIALS environment variable no longer triggers an unknown runtime option warning at server startup.
  • Fixed: Setting MultiplayerEntityActorBase.IsTicking from true to false at runtime will now correctly stop internal timer. This happens for example when a Season ends in a Division.
  • Fixed: Kicking a guild member from LiveOps Dashboard now updates remaining members' roles, like a normal kick would.
  • Fixed: The "session start handler took too long" error now includes per-handler timings for OnClientSessionHandshakeAsync, OnSessionStartAsync, and OnNewOwnerSession (or OnClientSessionHandshake and OnClientSessionStart for multiplayer entities), making it easier to identify which handler caused the timeout.
  • Fixed: If an experiment was still active while it was removed from the game config, its subsequent ServerEventExperimentInfo analytics events now have IsActive parameter value false (or 0) rather than true (or 1).
  • Fixed: RandomPCG fields in analytics events are now ignored by the BigQuery analytics sink. Their internal seed was not serializable.
  • Fixed: When a player gets assigned to an experiment's control group, the PlayerEventExperimentAssignment analytics event now correctly sets the VariantAnalyticsId equal to the ControlVariantAnalyticsId configured in the PlayerExperiments game config library. Previously, VariantAnalyticsId for control group was null (or missing value, in the case of BigQuery analytics).
  • Fixed: Fixed a case where an Entity could get stuck in early server boot. If an entity received a message very early in the server boot from another node, it could fail with error message Entity ... is in WaitingShardStart state but shard is in unexpected phase Running leaving the entity stuck forever until server restart.
  • Fixed: Added workaround for certain cases of persistent MissingContent errors for dynamic-content in-app purchases. It has been seen that Apple App Store purchases sometimes have a stale receipt in the initial validation of a purchase, leading to validation failure, but then the receipt is up to date on subsequent re-validation attempts (done on client app launch). Previously, with dynamic-content purchases, the initial failure would lead to the designated dynamic content being no longer available for the re-validation attempts, leading to persistent failures with MissingContent purchase result. Now, the dynamic content is retained until a successful purchase of the product; this way, the purchase re-validation can eventually succeed.
  • Fixed: IAPManager now detects duplicate per-platform product IDs at store initialization and reports a clear error instead of throwing an opaque ArgumentException from Unity Purchasing.
  • Fixed: dotnet ef migrations add now fails early with a clear error if the ModelSnapshot.cs file is read-only (e.g. in Perforce), instead of writing migration files and then failing on the snapshot update.
  • Fixed: ScheduleExecuteOnActorContext() with a time in the past no longer emits spurious overload warnings.
  • Fixed: Nullable types like MetaTime? are now rendered correctly in Model Inspector.
  • Fixed: Fixed $type mapping in admin API's JSON deserialization to also accept generic MetaSerializable types. Previously, it would reject generic types such as MyType<MyOtherType>, leading in particular to bogus errors in generated forms in the dashboard.
  • Fixed: Player sessions would sometimes fail to start after a new game config had been published, getting internal error 1310 (resource_activation_failed) due to client-side exception "Failed to open download cache config [...]". This happened in projects with multiplayer entities, such as league divisions. The client has been fixed to permit starting the session before it has downloaded multiplayer entities' game configs. MultiplayerEntityClientBase.Phase is MultiplayerEntityClientPhase.LoadingEntity while the client is downloading the entity's game config in the background.
  • Fixed: Failing actions no longer produce duplicated "Failed to execute action" log messages.
  • Fixed: When starting Local Server from Unity Editor menu, server build time no longer contributes to timeout.

LiveOps Dashboard ​

Complete List
  • Added: MAbbreviateNumber now allows you to explicitly specify which words to use for singular and plural amounts. This covers use cases where simply adding an s to the end of the unit word to represent plural numbers is not sufficient.
  • Added: IGeneratedUiFilterProps now contains fieldInfo to allow custom UI element selection using fieldTypeHint.
  • Added: Generated Forms and Views now support byte[] fields via file upload and download.
  • Added: Client logs in Incident Reports now have a copy-to-clipboard button.
  • Added: Stack traces in Incident Report client logs are now simplified by default.
  • Added: The MCollapse component now has a new keepContentAlive prop to allow you to prevent content from being unmounted/mounted as you close/re-open the collapse. This can make it easier to manage complex state inside a collapse.
  • Added: The MCard component now has a new stickyHeader prop. This keeps the card's header section visible even when the card is taller than the browser window.
  • Added: "View logs" buttons on player event log, purchase history, and subscription history entries that open Grafana Loki filtered to the player and the entry's time window.
  • Added: MCollapse component now has an optional isOpen prop that allows you to control the open/closed state of the collapse from outside the component.
  • Added: MClipboardCopy component now has an optional title prop that customizes the hover tooltip on the icon button variant and the button label on the full-size variant (replacing the previous slot-based label).
  • Added: Event Log entries now show the full date alongside the time making it easier to understand when an event happened.
  • Changed: The improved page titles, as added in R36, have been iterated on and improved further after customer feedback. Browser tab titles now use the format "subject - action" to make it easier to differentiate between multiple different tabs with the same action but different subjects.
  • Changed: Improved the UI of the Reconnect Devices modal in the player details page.
  • Changed: useGeneratedUiFieldForm() output validationError is now string | undefined instead of string | null.
  • Changed: GeneratedUiFormDynamicComponent param context-obj has been renamed to root-obj.
  • Changed: IGeneratedUiFieldTypeSchema.useAsContext is renamed to useAsRoot.
  • Changed: IGeneratedUiFieldInfo.context has changed type from [{ key: string; value: any }] | undefined to Record<string, any>.
  • Changed: IGeneratedUiFilterProps.serverContext is renamed to context and may no longer have value undefined.
  • Changed: IGeneratedUiFilterProps.page was always undefined and has been removed.
  • Changed: The signature of routeParamToSingleValue() has changed. It now takes the full route.params object and the name of the parameter as a string.
  • Changed: The isOpenByDefault prop was removed from the MCollapse component. Use isOpen instead to control whether the collapse starts open or closed.
  • Changed: MRawDataCard has moved from unstable to stable, becoming more performant and easier to navigate along at the same time.
  • Changed: MRawDataCard now takes a sources array instead of flat data/label props, allowing multiple sources to be shown with a single card.
  • Changed: The Runtime Options view on the environment details page now uses the new data explorer layout, which adds the ability to search through the options.
  • Changed: The SDK package no longer ships with the deprecated Cypress-based integration tests.
  • Changed: The LiveOps Dashboard now requires pnpm 11. pnpm 11 reads its configuration from pnpm-workspace.yaml instead of package.json, and the build-dependency allow-list moves to a new allowBuilds map. See the Update to pnpm 11 migration guide for the upgrade steps.
  • Fixed: Invalid experiments (e.g., those with missing config data) are no longer shown on the LiveOps Dashboard timeline.
  • Fixed: User authentication token expiration detection did not trigger if the server had been restarted.
  • Fixed: Experiment patch visualization in the game config details view now correctly shows changes when a patch sets a null field to an array or object value.
  • Fixed: Size estimations in JSON downloads (eg: in entity exports) were sometimes wildly incorrect - they are now correct.
  • Fixed: Fixed missing validation check for the initial state of a generated form. This resolves an issue where the user sometimes had to edit unrelated values before being able to submit the form.
  • Fixed: MCard no longer emits the headerClick event when clickableHeader is not set, preventing unintended side effects.
  • Fixed: Fixed bogus "Invalid Incident Type" warning on the "Player Incidents of Type" view.
  • Fixed: On the player detail page, the Offer Groups card, as well as cards for custom kinds of activables, take into account the experiments the player is in. In particular, Offer Groups defined only in experiment variants but not in the baseline were previously never shown here, but are now shown if the player is in the relevant variants.
  • Fixed: Missing content in the player's OfferGroupsCard due to a slot name mismatch.
  • Fixed: Improved layout and styling of connection icons in the Event Log views.
  • Fixed: MInputSwitch incorrectly showing focus outlines on the label element when no label was provided.
  • Fixed: MInputSingleSelectDropdown and MInputSingleSelectAsyncDropdown no longer show the background page through the dropdown's option list when it is over-scrolled.
  • Fixed: Pre-highlighted events in Event Log views were sometimes not visible when inside folded groups.
  • Fixed: Viewing matchmaker details no longer fails when a bucket contains a deleted player.
  • Fixed: In the Servers tab of the Environment page, Node uptime no longer shows bogus values for nodes that are not running.
  • Fixed: The "Balance automatically" button for experiment variant weights could produce incorrect weights.
  • Fixed: An issue where the MInputNumber component would not clear its value when entered and cleared repeatedly.
  • Fixed: The MViewContainer, MSingleColumnLayout, and MTwoColumnLayout components now control margins on a page consistently. You no longer need to add manual margins to the content inside them.
  • Fixed: Long entity type names no longer break the current entities list on the environment details page.
  • Fixed: MInputSingleSelectSwitch vertical alignment and layout-shift issues, especially in the small-size variant.

Samples ​

Complete List
  • Changed: The Idler sample's matchmaking flow now uses MetaRequest/MetaResponse instead of manual MetaMessage listeners, demonstrating the simpler async request-response pattern. See Client-Server Requests for details.
  • Removed: Removed obsolete launchSettings.json files from all sample projects.

Documentation ​

Complete List
  • Added: New Client-Server Requests documentation for the MetaRequest/MetaResponse system.
  • Added: New Guild Discovery documentation covering how Guild Search and Guild Recommendation work, including the GuildDiscoveryInfoBase / GuildDiscoveryPlayerContext fragments.
  • Added: New Upgrading to Unity IAP v5 guide for migrating from Unity Purchasing v4 to v5, including Apple StoreKit 2 server configuration.
  • Added: New Copying a Database Between Environments guide for archive-based DB migration between cloud environments.
  • Added: New AI Assistants section covering practical ways to use AI coding tools with Metaplay (Custom GPT, llm-docs MCP server, portal MCP server).
  • Added: New Custom Comparable Properties section in the Implementing Player Segments guide, documenting the new ICustomComparable interface.

Notable CLI Changes ​

  • New Command: metaplay init ci - Create build & deploy server CI jobs for various CI systems.

    • Supports GitHub, Bitbucket, and generic scripts for other CI systems.

  • New Command: metaplay image pull - Pull an image from a remote environment to your local machine.

    • Enables building workflows for promoting an image from one environment to another, without needing to re-compile.

  • New Command: metaplay image list - List remote images in an environment.

  • Improved metaplay init project - The command now builds the set of files to write in memory first.

    • It now detects conflicts before writing any files, and no longer overwrites existing .meta files.

  • Significantly Improved Error Messages - Errors are now easier to read and give more actionable information.

Migration Guide for All Customers ​

.NET 9 Support Removed

Starting with this release, .NET 10 is the only supported runtime version. If your project still targets .NET 9, upgrade to .NET 10 before upgrading to this release. Follow the Release 36 migration guide For All Metaplay Projects.

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.

Replace Legacy Integration Test Script with CLI Command

The legacy Scripts/integration-tests.py Python script has been removed. Use the metaplay test integration CLI command instead.

Migration Steps:

  1. Update your CI pipelines to use the new CLI command:

    bash
    # Old command #
python MetaplaySDK/Scripts/integration-tests.py
# New command #
metaplay test integration

  2. Remove any Python environment setup for the integration tests (installing colorama and PyYAML dependencies is no longer needed).

For more information about integration testing, see the Integration Testing documentation.

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.

shell
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:

Switch to Prebuilt Code Analyzers

The Metaplay code analyzers are now shipped as prebuilt DLLs instead of project references. This eliminates file-locking errors during parallel builds.

Migration Steps:

  1. Add the following import to your Directory.Build.props file, after the MetaplaySDKPath property is defined:

    Backend/Directory.Build.props
    xml
    </PropertyGroup>

<Import Project="$(MetaplaySDKPath)/Backend/Metaplay.Analyzers.targets" /> 
</Project>

  2. Remove all ProjectReference entries for Metaplay.CodeAnalyzers and Metaplay.CodeAnalyzers.Shared that have <OutputItemType>Analyzer</OutputItemType> from your .csproj files. These blocks look like:

    xml
    <!-- Remove these blocks from all .csproj files: -->
<ProjectReference Include="$(MetaplayServerPath)\CodeAnalyzers\Metaplay.CodeAnalyzers.csproj">
  <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
  <OutputItemType>Analyzer</OutputItemType>
</ProjectReference>
<ProjectReference Include="$(MetaplayServerPath)\CodeAnalyzers.Shared\Metaplay.CodeAnalyzers.Shared.csproj">
  <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
  <OutputItemType>Analyzer</OutputItemType>
</ProjectReference>

    The affected files are typically Server.csproj, SharedCode.csproj, BotClient.csproj, and any test or tool projects that referenced the analyzers. Do not remove the regular ProjectReference to Metaplay.Cloud.csproj or other non-analyzer references.

  3. If your project uses a .sln solution file, remove the analyzer projects from it. These projects are no longer needed in the solution since the analyzers are now consumed as prebuilt DLLs. Building them as part of the solution would produce artifacts that are not actually used. Run the following from your Backend/ directory:

    bash
    Backend$ dotnet sln remove <path-to-sdk>/Backend/CodeAnalyzers/Metaplay.CodeAnalyzers.csproj
Backend$ dotnet sln remove <path-to-sdk>/Backend/CodeAnalyzers.Shared/Metaplay.CodeAnalyzers.Shared.csproj
Backend$ dotnet sln remove <path-to-sdk>/Backend/Attributes/Metaplay.Attributes.csproj

    Alternatively, you can open the .sln file in a text editor and remove the Project entries and their corresponding GlobalSection entries for Metaplay.CodeAnalyzers, Metaplay.CodeAnalyzers.Shared, and Metaplay.Attributes.

    Note: Metaplay.Attributes is still referenced as a normal ProjectReference by Metaplay.Cloud.csproj. MSBuild resolves this automatically even when the project is not in the solution. Some IDEs may show a warning about this — it can be safely ignored, or you can keep Metaplay.Attributes in the solution if preferred.

Apply Database Schema Migrations

Metaplay's built-in database schema has changed, and you need to apply the migration steps to your project.

Migration Steps:

  1. Generate the database schema migration code with:

    bash
    # Install or update the EFCore tool:
Backend/Server$ dotnet tool install -g dotnet-ef
# Then, generate the migration code:
Backend/Server$ dotnet ef migrations add MetaplayRelease37

  2. Then, add the generated files to your project's source control. For example, using Git:

    bash
    Backend/Server$ git add .
Backend/Server$ git commit -m "Database schema migrations"

The migration steps will be automatically applied when you deploy the updated game server into an environment.

Potentially Large Migrations

This release changes the default column type for strings from TEXT to LONGTEXT. If you have large tables with string columns, this migration can take a long time. To see which tables are affected, review the generated Backend/Server/Migrations/*_MetaplayRelease37.cs file. To avoid the migration and keep the columns as is, mark the fields with [Column(TypeName = "TEXT")] attribute, and delete and generate the migration code.

Note that column type updates to MetaplaySDK internal types WebLoginAuthorizations.LoginMethod, StaticGameConfigs.FailureInfo, MetaInfo.Version, Localizations.FailureInfo are expected, and reviewed to be safe.

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 from the MetaplaySDK/Frontend/DefaultDashboard directory to your dashboard project:

    • tsconfig.app.json
    • Update the references path in tsconfig.app.json, ensuring it points to the tsconfig.libraries.json file in the MetaplaySDK/Frontend directory. This is typically of the form "../../MetaplaySDK/Frontend/tsconfig.libraries.json".

Update to pnpm 11

The LiveOps Dashboard now uses pnpm 11. The most impactful change is that pnpm 11 no longer reads configuration from the pnpm field in package.json, and it consolidates the build-dependency allow-list into a new allowBuilds map in pnpm-workspace.yaml. See the pnpm v10 to v11 migration guide for the complete list of changes; for a typical Metaplay project the steps below are all that's required.

Migration Steps:

  1. Upgrade your local pnpm to v11. The recommended way is via Corepack, which activates the version pinned by the project:

    bash
    corepack enable
corepack prepare pnpm@11.1.2 --activate
pnpm --version # should print 11.1.2

    Alternatively, run pnpm self-update 11. (Recent Node.js releases no longer bundle Corepack; if corepack is not found, install it first with npm install -g corepack@latest.)

  2. Run the pnpm configuration codemod from your repository root. It migrates settings out of the package.json pnpm field and .npmrc into pnpm-workspace.yaml:

    bash
    pnpx codemod run pnpm-v10-to-v11

    The codemod is mechanical and may not migrate every setting. It might also not result in any diff, but review what it did, then move to the next step.

  3. Remove obsolete configs that do nothing anymore in pnpm 11, which merges onlyBuiltDependencies (along with neverBuiltDependencies, ignoredBuiltDependencies, and onlyBuiltDependenciesFile) into a single allowBuilds map of name: true | false.

    pnpm-workspace.yaml
    yaml
    onlyBuiltDependencies:    
  - '@parcel/watcher'
  - bootstrap-vue
  - esbuild

  4. Add the new allowBuilds map to allow build-scripts that are by default disallowed by pnpm 11. If you skip this, pnpm install fails with ERR_PNPM_IGNORED_BUILDS and the affected packages' build scripts are silently skipped.

    pnpm-workspace.yaml
    yaml
    allowBuilds:              
  '@parcel/watcher': true
  bootstrap-vue: true
  esbuild: true

  5. Continue with the Clear and Recreate the Dashboard Dependencies step below to reinstall against pnpm 11.

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.

Migration Steps:

  1. First, make sure you're on the latest version of the Metaplay CLI by running metaplay update cli or installing the CLI using instructions at Metaplay CLI.
  2. Next, remove any files that Node has cached in your project. This will lead to a fresh install of all dependencies.
    • Run metaplay dev clean-dashboard-artifacts from within your project folder. This clears any currently installed dependencies and built files.
    • Delete the pnpm-lock.yaml file from the root of your project. This clears the cached dependency versions.
  3. Run metaplay dev dashboard from within your project folder. This recreates all of the above files and folders with the correct dependencies, and runs the dashboard in development mode.
Replace isOpenByDefault with isOpen in MCollapse

The isOpenByDefault prop in the MCollapse component has been removed. Use the isOpen prop instead to set the initial open/closed state of the collapse.

Migration Steps:

  1. Replace all uses of is-open-by-default with is-open in your dashboard templates:

    pug
    MCollapse(is-open-by-default)
MCollapse(is-open)

    Or

    pug
    MCollapse(:is-open-by-default="someBooleanCondition")
MCollapse(:is-open="someBooleanCondition")
Use the title prop on MClipboardCopy for the full-size button label

The full-size variant of MClipboardCopy no longer takes its button label from the default slot. Use the new title prop instead. On the icon-button variant, the same title prop customizes the hover tooltip — set it there too if you previously relied on a default "Copy" tooltip.

Migration Steps:

  1. On full-size variants, move any custom slot label into the title prop:

    pug
    MClipboardCopy(:contents="value" full-size) Copy Player Data
MClipboardCopy(:contents="value" title="Copy Player Data" full-size)

  2. On icon-button variants, set title to customize the hover tooltip:

    pug
    MClipboardCopy(:contents="value")
MClipboardCopy(:contents="value" title="Copy Player ID")
Migrate MRawDataCard to the Multi-Source API

MRawDataCard now takes a sources array instead of flat data/label props. The hideClipboardCopy prop is gone (each source gets its own copy button), and the component is now safe to render unconditionally — if every source is gated off by developer-UI settings, the card renders nothing.

Migration Steps:

  1. Replace flat-prop usage with a sources array:

    pug
    MRawDataCard(
  :data="playerModel"
  label="Player Model"
  )
MRawDataCard(:sources="[{ data: playerModel, label: 'Player Model' }]")

  2. Combine adjacent cards into a single card with multiple sources:

    pug
    MRawDataCard(:data="a", label="A")
MRawDataCard(:data="b", label="B")
MRawDataCard(:sources="[{ data: a, label: 'A' }, { data: b, label: 'B' }]")

  3. Move showAlways onto the individual source entry, and remove any hideClipboardCopy usage — a copy button is now provided per source automatically.

    pug
    MRawDataCard(
  :data="playerModel"
  label="Player Model"
  :show-always="showInProd"
  hide-clipboard-copy
  )
MRawDataCard(:sources="[{ data: playerModel, label: 'Player Model', showAlways: showInProd }]")
Remove Manual Margins Inside MViewContainer, MSingleColumnLayout, and MTwoColumnLayout

These layout components now apply consistent vertical spacing to their children. Manual tw-mt-* / tw-mb-* / mb-* classes that you previously added to space components will now stack on top of the built-in spacing and produce gaps that are too large.

Migration Steps:

  1. In each view that uses MViewContainer, MSingleColumnLayout, or MTwoColumnLayout, remove margin utility classes from direct children of those layouts.

    pug
    MViewContainer(...)
  ...
  MRawDataCard(class="tw-mt-5" :sources="[{ data: foo, label: 'foo' }]")
  MRawDataCard(:sources="[{ data: foo, label: 'foo' }]")

  2. Remove class="tw-mb-4" (and similar) from the layout components themselves — vertical spacing between sections is now handled by MViewContainer.

    pug
    MSingleColumnLayout(class="tw-mb-4")
MSingleColumnLayout
  ...

  3. For multiple content blocks placed directly in MViewContainer's default slot, remove margin or spacing classes and wrap them in MTwoColumnLayout to get consistent spacing.

    pug
    MViewContainer(...)
  template(#overview)
    MyOverviewCard
  div(class="tw-space-y-4 tw-mt-4")
    MyContentCard
    MyOtherContentCard
  MTwoColumnLayout
    MyContentCard
    MyOtherContentCard

  4. Run your dashboard locally and visually verify that pages still look correct.

Update Consumers of MetaFormFieldContextAttribute

IGeneratedUiFieldInfo.context has changed type from [{ key: string; value: any }] | undefined to Record<string, any>. All custom Generated UI Components that access the context set by a MetaFormFieldContextAttribute must be updated.

Migration Steps:

  1. Replace the uses of context by accessing it as a dictionary instead of a list

    ts
    const myContextValue = props.context?.find((val) => (val.key === 'myCustomContextKey'))?.value 
const myContextValue = props.context.myCustomContextKey
Update Filtering Functions for Custom Generated UI Components

The props given to the filter function in addGeneratedUiFormComponent() and addGeneratedUiViewComponent() have been changed as follows:

  • serverContext is renamed to context and may no longer have value undefined.
  • fieldInfo has been added to the props, to allow filtering on field metadata.
  • page was always undefined and has been removed.

Migration Steps:

  1. Update filter functions given to addGeneratedUiFormComponent() and addGeneratedUiViewComponent():

    gameSpecific.ts
    ts
    initializationApi.addGeneratedUiFormComponent(
{
    filterFunction: (props, type) => {
        return props.serverContext?.myCustomContextKey === 'useMyCustomComponent'
        return props.context.myCustomContextKey === 'useMyCustomComponent'
    },
    vueComponent: () => import('./MyCustomComponent.vue')
}
)
Update Calls to routeParamToSingleValue()

The signature of routeParamToSingleValue() has changed. It now takes the full route.params object and the name of the parameter as a string, instead of the resolved parameter value directly. This makes the function self-contained: it validates that the parameter exists and is a string, throwing a descriptive error if not.

Migration Steps:

  1. Update all calls to routeParamToSingleValue() in your custom dashboard views:

    ts
    import { useRoute } from 'vue-router'
const route = useRoute()

const myId = routeParamToSingleValue(route.params.id) 
const myId = routeParamToSingleValue(route.params, 'id')

    If you previously guarded the call with a manual undefined check, you can remove it — the function now throws a descriptive error automatically:

    ts
    if (route.params.id === undefined) throw new Error('id route param is required.') 
const myId = routeParamToSingleValue(route.params.id) 
const myId = routeParamToSingleValue(route.params, 'id')

For Games With AppleStore:AppleSharedSecret in Server Options ​

The following affects projects that specify AppleSharedSecret (in section AppleStore) in server options (by default in Backend/Server/Config/Options.*.yaml):

Migrate Apple Shared Secret to a Secrets Manager

To support storing secrets outside the project repository, the plain AppleSharedSecret option has been deprecated. The secret should instead be stored in a secrets management system, such as Kubernetes secrets. AppleSharedSecret continues to work for now, but a warning will be logged at server startup if it is set.

The Shared Secret is used when validating App Store in-app purchases. It allows requesting information from Apple's servers about players' auto-renewing subscriptions.

Migration Steps:

  1. Identify each .yaml options file where AppleSharedSecret is specified. The following steps will need to be repeated for each environment using such an options file. Note that a single options file may be used by multiple environments, in particular Options.base.yaml.

  2. Move the value of the AppleSharedSecret option to a secret management system. See Supported Secret Sources for the possible ways to store secrets. The recommended way is to use Kubernetes secrets:

    shell
    # Below, replace my-environment with the environment ID.
# Your local file apple-shared-secret.txt must contain the Shared Secret value previously set in the `AppleSharedSecret` option.
metaplay secrets create my-environment user-apple-shared-secret --from-file=secret=apple-shared-secret.txt
    Backend/Server/Config/Options.my-environment.yaml
    yaml
    
AppleStore:
  AppleSharedSecret: 0123456789abcdef0123456789abcdef
  AppleSharedSecretPath: "kube-secret://user-apple-shared-secret#secret"

  3. As the secret has been previously stored in the repository and therefore remains in its version history, you should consider rotating the secret.

    Important: To avoid disruption to IAP validation, this step should not be done at the time of the rest of the SDK update, but instead during a game update, when the updated server is still in maintenance mode. This applies especially to the production environment.

    Follow Apple's developer documentation to regenerate the secret. It may be either a primary or an app-specific secret. Then, update the secret in the correct environment. For example, with Kubernetes secrets:

    shell
    # Below, replace my-environment with the environment ID.
# Your local file apple-shared-secret.txt must contain the newly generated Shared Secret.
metaplay secrets update my-environment user-apple-shared-secret --from-file=secret=apple-shared-secret.txt

For Games Upgrading to Unity Purchasing v5 (Optional) ​

Unity Purchasing v5 is now supported. Upgrading is not required by Metaplay — existing Unity Purchasing v4 projects continue to work without changes.

If your game ships on Google Play, also check your Unity Purchasing version against Google's Play Billing Library deprecation schedule. Older v4 releases ship outdated Play Billing Library versions that Google no longer accepts for new app releases or updates. Unity Purchasing v4.14 (which ships Play Billing Library 8.0.0) and v5.x both satisfy Google's requirements through August 31, 2027 — so v5 is not required for Google Play compliance, but you should be on at least v4.14 if you intend to stay on the v4 line.

Migrate to Unity Purchasing v5

Read the dedicated Upgrading to Unity IAP v5 guide. It covers updating the Unity Purchasing package and the Apple In-App Purchase key needed for v5 subscription state queries.

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.

Migrate Session Retention Timeouts to Server-Authoritative SessionLingerDuration

Server-side session retention is now configured by SessionOptions.SessionLingerDuration (default 00:01:00). The client receives this value at handshake and uses it for all pause-related thresholds, replacing two client-side ConnectionConfig fields.

Migration Steps:

  1. Migrate ConnectionConfig.MaxSessionRetainingPauseDuration to SessionOptions.SessionLingerDuration.

    ApplicationStateManager.cs
    csharp
    new ConnectionConfig
{
    MaxSessionRetainingPauseDuration = TimeSpan.FromSeconds(90), 
};
    Options.base.yaml
    yaml
    Session:                          
  SessionLingerDuration: 00:01:30

  2. Migrate customized SessionActor.ShutdownPolicy to SessionOptions.SessionLingerDuration.

    SessionActor.cs
    csharp
    public class SessionActor : SessionActorBase
{
    protected override AutoShutdownPolicy ShutdownPolicy
        => AutoShutdownPolicy.ShutdownAfterSubscribersGone(lingerDuration: TimeSpan.FromSeconds(90)); 
}
    Options.base.yaml
    yaml
    Session:                          
  SessionLingerDuration: 00:01:30

  3. Remove uses of ConnectionConfig.MaxNonErrorMaskingPauseDuration.

    MaxNonErrorMaskingPauseDuration is now automatically configured to the session linger length and does not need to be configured.

    ApplicationStateManager.cs
    csharp
    new ConnectionConfig
{
    MaxNonErrorMaskingPauseDuration = TimeSpan.FromSeconds(20), 
};
Migrate ConnectionConfig.SessionResumptionAttemptMaxDuration to MaxReconnectingForegroundDuration

SessionResumptionAttemptMaxDuration used to compute wall-clock time which had unexpected behavior if connection was lost when app was on background. The new MaxReconnectingForegroundDuration field counts foreground time only, so application background time is excluded from the budget.

Migration Steps:

  1. Migrate any customizations of SessionResumptionAttemptMaxDuration to MaxReconnectingForegroundDuration:

    ApplicationStateManager.cs
    csharp
    MetaplayClient.Initialize(new MetaplayClientOptions
{
    ConnectionConfig = new ConnectionConfig
    {
        SessionResumptionAttemptMaxDuration = TimeSpan.FromSeconds(30), 
        MaxReconnectingForegroundDuration   = TimeSpan.FromSeconds(30), 
    },
    /* ... */
});
Update Callers of GuildSearchActorBase.EntityIdOnCurrentNode

GuildSearchActorBase.EntityIdOnCurrentNode has been removed. Use the new GuildSearchActorBase.GetLocalNodeEntityId() helper to resolve the local node's service EntityId on demand.

Migration Steps:

  1. Replace any uses of EntityIdOnCurrentNode:

    csharp
    EntityAskAsync(GuildSearchActorBase.EntityIdOnCurrentNode, ...); 
EntityAskAsync(GuildSearchActorBase.GetLocalNodeEntityId(), ...);
Update Callers of GetAllEnvironmentConfigs()

DefaultEnvironmentConfigProvider.GetAllEnvironmentConfigs() now returns IReadOnlyList<EnvironmentConfig> instead of EnvironmentConfig[]. This avoids an unnecessary array allocation on every call. If your project calls this method, update the receiving variable type and replace .Length with .Count.

Migration Steps:

  1. Update the variable type and array access:

    csharp
    EnvironmentConfig[] configs = provider.GetAllEnvironmentConfigs(); 
IReadOnlyList<EnvironmentConfig> configs = provider.GetAllEnvironmentConfigs();

  2. Replace .Length with .Count:

    csharp
    for (int i = 0; i < configs.Length; i++) 
for (int i = 0; i < configs.Count; i++)
Remove Override of ParseLegacyVersion1PoolPage()

ParseLegacyVersion1PoolPage() has been removed from PersistedGuildDiscoveryPool. Guild discovery pool data in the legacy schema version 1 format is now silently dropped. If your project overrides this method, remove the override and any helper types that were only used by it.

Migration Steps:

  1. Remove the ParseLegacyVersion1PoolPage() override from your PersistedGuildDiscoveryPool-derived class:

    csharp
    protected override GuildDiscoveryPoolPage ParseLegacyVersion1PoolPage(byte[] payload) 
{ 
    // ...
}
Suppress Deprecation Warning for MetaplayWebhookController

MetaplayWebhookController is now deprecated to discourage future use. The controller is still supported, but any existing use will cause warnings. You must manually suppress the warnings.

Migration Steps:

  1. Suppress the deprecation warning in your MetaplayWebhookController-derived classes:

    csharp
    #pragma warning disable CS0618 // MetaplayWebhookController is supported, but deprecated to discourage future use
public class MyWebhookController : MetaplayWebhookController
#pragma warning restore CS0618 
{
    // ...
}
Update Uses of MetaFormUseAsContextAttribute

MetaFormUseAsContextAttribute has been renamed to MetaFormUseAsRootAttribute to clarify the behavior. Following the renaming, GeneratedUiFormDynamicComponent param context-obj has been renamed to root-obj, and IGeneratedUiFieldTypeSchema.useAsContext has been renamed to useAsRoot. If you have custom Generated UI components, you need to update them as follows:

Migration Steps:

  1. Update Attribute name:

    csharp
    [MetaFormUseAsContext] 
[MetaFormUseAsRoot] 
class MyObjectAsRootValue

  2. Update any custom uses of GeneratedUiFormDynamicComponent:

    pug
    GeneratedUiFormDynamicComponent(
    :context-obj="..."
    :root-obj="..."
)

  3. Update any custom uses of IGeneratedUiFieldTypeSchema:

    ts
    const fieldSchema: IGeneratedUiFieldTypeSchema = ...;
if (fieldSchema.useAsContext) 
if (fieldSchema.useAsRoot) 
{
    ...
}
Set Write Mode for ConfigArchiveBuildUtility.FolderEncoding.WriteToDirectory() Calls

WriteToDirectory(archive, path) is now deprecated in favor of WriteToDirectory(archive, path, mode). You should configure the desired write mode for your use case. In most cases, you should use DeleteExistingFiles or DeleteExistingFilesKeepMetaFiles, but in special cases you may use ThrowOnExtraFiles or KeepExistingFiles.

Migration Steps:

  1. Use DeleteExistingFilesKeepMetaFiles for files written into Unity Streaming Assets:

    csharp
    ConfigArchiveBuildUtility.FolderEncoding.WriteToDirectory(assetsArchive, AssetsPath); 
ConfigArchiveBuildUtility.FolderEncoding.WriteToDirectory(assetsArchive, AssetsPath, ConfigArchiveBuildUtility.FolderEncoding.DirectoryWriteMode.DeleteExistingFilesKeepMetaFiles);

  2. Use DeleteExistingFiles in other cases when existing files should be removed first:

    csharp
    ConfigArchiveBuildUtility.FolderEncoding.WriteToDirectory(archive, ToolPath); 
ConfigArchiveBuildUtility.FolderEncoding.WriteToDirectory(archive, ToolPath, ConfigArchiveBuildUtility.FolderEncoding.DirectoryWriteMode.DeleteExistingFiles);
Update the Signature of GuildActor.ShouldAcceptPlayerJoin()

The signature GuildActor.ShouldAcceptPlayerJoin() has been updated to allow for future extensions without API changes. If you have overridden this method, you must update the signature.

Migration Steps:

  1. Update signature and extract arguments from subclasses

    csharp
    protected override bool ShouldAcceptPlayerJoin(EntityId playerId, GuildMemberPlayerDataBase playerData, bool isInvited) 
protected override bool ShouldAcceptPlayerJoin(ShouldAcceptPlayerJoinArgs args) 
{
    EntityId member = playerId; 
    EntityId member = args.PlayerId; 

    GuildMemberPlayerDataBase data = playerData; 
    GuildMemberPlayerDataBase data = args.PlayerData; 

    if (isInvited) 
    if (args is ShouldAcceptPlayerJoinArgs.InvitationCodeJoinArgs inviteArgs) 
    {
    }
}
Replace Auto-Incrementing Database Tables with Explicit Keys

EF Core database tables with auto-incrementing columns are no longer supported. As the database is sharded, each shard has its own autoincrementing domain, and this can cause conflicts when resharding content between databases. To simplify behavior and unify behavior across database engines, auto-incrementing tables are now disallowed.

This applies to columns marked with [DatabaseGenerated(DatabaseGeneratedOption.Identity)]. In case the column was implicitly auto-incrementing due to EF Core implicitly marking integral primary keys as auto-incrementing, you do not need to change anything.

Migration Steps:

  1. Disable auto-incrementing:

    csharp
    [Table("IntKeyedTable")]
public class IntKeyedTable : IPersistedItem
{
    [Key]
    [PartitionKey]
    [DatabaseGenerated(DatabaseGeneratedOption.Identity)] 
    public long Key { get; set; }

    // more data
}

  2. Use the current time as the key when inserting.

    You may use current milliseconds, or microseconds if more is needed.

    csharp
    IntKeyedTable item = new IntKeyedTable
{
    Key = (DateTime.UtcNow - DateTime.UnixEpoch).Ticks / TimeSpan.TicksPerMicrosecond, 
    // ...
};
await db.InsertAsync(item);
Use Explicit Column Types for Unsigned Integer Columns

uint and ulong columns no longer have implicit column types. The names for the these unsigned types depends on the database engine used. To use unsigned columns, you need to set the column type manually.

Migration Steps:

  1. Set unsigned column type manually:

    csharp
    [Table("MyTable")]
public class MyTable : IPersistedItem
{
    ...

    [Column(TypeName = "INTEGER UNSIGNED")] // Using MySQL syntax
    public uint UnsignedColumn { get; set; }

    [Column(TypeName = "BIGINT UNSIGNED")] // Using MySQL syntax
    public ulong UlongColumn { get; set; }
}
Update Calls to PlayerIncidentStorage.SerializeAndPersistIncidentAsync()

PlayerIncidentStorage.SerializeAndPersistIncidentAsync() has been renamed to TrySerializeAndPersistIncidentAsync() and now returns a bool indicating whether the incident was new and valid. If incident already exists or is malformed, the method returns false.

Migration Steps:

  1. Rename the method and call InformPlayerEntityOfIncident() only for new incident:

    csharp
    await PlayerIncidentStorage.SerializeAndPersistIncidentAsync( 
bool wasWritten = await PlayerIncidentStorage.TrySerializeAndPersistIncidentAsync( 
    playerId: playerId,
    report: report,
    source: PlayerIncidentStorage.IncidentSource.ServerGenerated,
    country: playerLocation);
if (wasWritten) 
{ 
    PlayerIncidentStorage.InformPlayerEntityOfIncident(
        playerId: playerId,
        report: report,
        sourceEntity: this);
}

For Games With Custom GameConfig Source Data ​

The following changes affect projects that have custom IGameConfigSourceData implementations or custom build pipelines:

Update IGameConfigSourceData.Get() to Accept CancellationToken

The IGameConfigSourceData.Get() method now takes a CancellationToken parameter for cancellation support during builds. The old parameterless Get() is preserved as an [Obsolete] default interface method, so your project will still compile — but you will see deprecation warnings and a DebugLog.Warning at runtime until you migrate.

Migration Steps:

  1. Find all classes that implement IGameConfigSourceData and update their Get() method to accept a CancellationToken:

    csharp
    public class MyCustomSourceData : IGameConfigSourceData
{
    public async Task<object> Get() 
    public async Task<object> Get(CancellationToken ct) 
    {
        return await LoadDataAsync(); 
        return await LoadDataAsync(ct); 
    }
}

  2. If your custom source data performs long-running operations (e.g., network requests, file I/O), pass the CancellationToken through to those operations. This allows builds to be cancelled mid-fetch.

  3. If your source data is trivial (e.g., returns in-memory data), you can accept the parameter and ignore it:

    csharp
    public Task<object> Get(CancellationToken ct) => Task.FromResult<object>(_data);

For Games With Custom Database Definitions ​

The following affects projects that define custom database tables or columns (custom IPersistedItem types, custom EF Core entities, or hand-written SQL writes):

Audit Custom Schemas for Stricter Database Writes

Starting with this release, your game server rejects database writes that would previously have been silently truncated or coerced. This affects cloud deployments using AWS Aurora MySQL, which historically allowed silent string truncation, integer clamping, and acceptance of zero dates.

Migration Steps:

  1. Audit your custom database schema definitions for write sites that could violate column constraints. For each custom IPersistedItem or EF Core entity, walk the columns and check the corresponding C# write site:

    • Bounded VARCHAR(N) columns receiving inputs that could exceed N characters — typical risk sources are user input (player display names, search terms), serialized exception or log messages, and externally-fetched data.
    • Integer columns narrower than INT (e.g. TINYINT, SMALLINT) receiving values from C# int / long types that could exceed the column's range.
    • NOT NULL columns where the write site might not always populate the field.

    Wherever a write could violate the constraint, add validation or explicit truncation/clamping at the call site.

  2. After deploying, monitor cloud-environment server logs as a safety net for any cases the audit missed:

    • Data too long for column 'X' — a string exceeded a VARCHAR(n) column.
    • Out of range value for column 'X' — a number didn't fit the column's integer type.
    • Incorrect <type> value: 'X' for column 'Y' — an invalid date or type coercion was attempted.
    • Field 'X' doesn't have a default value — a NOT NULL column was missing a value.

    Each occurrence indicates code that was previously writing values the database silently mangled. Address by fixing the offending write site.

  3. If you need more time to complete the audit without taking the behavior change, temporarily opt out by setting MySqlSqlMode to null. This reverts to the database's default behavior, where the database may silently coerce invalid writes (as Aurora does pre-R37).

    Backend/Server/Config/Options.base.yaml
    yaml
    Database:
  MySqlSqlMode: null

    The opt-out is intended as a short-term escape hatch. Re-enable strict mode (remove the override) once the audit is complete.

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:

shell
MyProject$ metaplay test integration