Highlights

New Feature: Business Metrics

You can now track your key performance indicators right from the LiveOps dashboard, no setup required. Head to the LiveOps dashboard metrics page to check it out.

New Feature: Client Patch Versions

Client-only patch releases can now be tagged with a Client Patch Version identifier and the Client Compatibility settings in the Metaplay LiveOps dashboard has been extended to support specifying client patch version requirements per client platform. This is useful for the ability to release non-critical fixes to clients without requiring a server update or forcing a client update, while maintaining the ability to force clients to update to a specific patch version per platform at a later time.

New Feature: LiveOps Events Timeline (preview)

The "LiveOps Events" page now has a visual timeline that you can use to organize and view all your events in. This first rollout introduces the concept of groups, rows and colors that can be used to organize your events. We will be working on more editing and navigation features for the next release and feedback is already welcome!

New Feature: Steam authentication

Metaplay now supports authenticating users by their Steam accounts on server login, see Implementing Steam Authentication for details!

Changes

Metaplay SDK

• OrderedDictionary -> MetaDictionary: The class OrderedDictionary has been renamed to MetaDictionary in preparation for supporting .NET9. This rename causes no change in functionality and any serialized data continues to be compatible. The reason for this is that .NET9 introduces System.Collections.Generic.OrderedDictionary which technically could co-exist with Metaplay.Core.OrderedDictionary but would necessitate using the namespace-qualified name of the class and would create the potential of accidentally using the system implementation where the Metaplay implementation was intended. See Migration Guide For Self-Service Customers for guidance on migrating your project.

• New MetaConfigId Reference Type: We've introduced MetaConfigId for optimizing the server memory footprint of games with large game configs and complicated experiments setups. MetaConfigId, which remains a simple config ID in memory, can be used in place of MetaRef, which resolves the referenced item into memory. For more information, see Using MetaConfigId Instead of MetaRef.

Complete List

• Added: Added support for Unity 6's 'WebAssembly 2023' targeting.
• Added: New BigQuery format option [BigQueryAnalyticsFormat(BigQueryAnalyticsFormatMode.ExtractDictionaryElements)] can be used to format dictionary-like objects as if dictionary elements were object fields.
• Added: Added new parameter SubscribeToAsync(..., bool allowMultiple = false) to opt-in to allowing multiple subscriptions between two entities.
• Added: Client's Incident Reports are now attempted to be uploaded in background to S3 instead of sending them in-band to game server using the game protocol. This improves the reliability of the game protocol as potentially large transfers are offloaded.
• Added: The entity event log (shown in the LiveOps Dashboard) now supports optionally including the analytics context and labels for each event. Until now, the context and labels were only sent to external analytics storage but not included in the event log. See Storage and Configuration for how to enable this.
• Added: Support for request-response type safety and deduction for EntityAskAsync(...) calls and [EntityAskHandler] definitions. You can opt in per request-response type pair by deriving them from EntityAskRequest<TResponse> and EntityAskResponse instead of plain MetaMessage.
• Added: Geolocation may now be spoofed in Unity Editor on Development servers and on Developer Players. See Why can't I see my location when I'm running a local server? in Geolocation Frequently Asked Quersions for details how to override the location.
• Added: Geolocation now supports MaxMind's city-precision database in addition to the default country database. See Enabling City-Precision Location.
• Added: IEntityClientContext now has EarlyUpdate. EarlyUpdate() is called for every entity context before Update() is called.
• Added: Storage Write API is now available for use to write analytics event data into BigQuery. Advantages of Using the Storage Write API:
  • Exactly-once Delivery Semantics: The Storage Write API ensures exactly-once delivery by using stream offsets, preventing duplicate messages within a stream.
  • Stream-level Transactions: You can write data to a stream and commit it as a single transaction. If a commit fails, it can be safely retried, ensuring data integrity.
  • Transactions Across Streams: Multiple workers can independently process data using their own streams. Once all workers complete their tasks, all streams can be committed as a single transaction.
  • Efficient Protocol: The API uses gRPC streaming, which is more efficient than REST over HTTP. It supports binary formats via protocol buffers, offering a more efficient wire format than JSON. Write requests are asynchronous with guaranteed ordering.
  • Schema Update Detection: If the table schema changes during streaming, the API notifies the client, allowing them to reconnect with the updated schema or continue with the existing connection.
  • Lower Cost: The Storage Write API is significantly more cost-effective than the older insertAll streaming API, with up to 2 TiB of data ingestion per month available for free.
  • Note: To use the Storage Write API, you must have bigquery.tables.updateData permissions.
• Added: Added support to authenticate and create accounts for users using Steam on Windows, Mac, and Linux.
• Added: DynamicEnum now supports declaring the enum values dynamically on initialization via a static method on the DynamicEnum derived class identified by DynamicEnumFactoryAttribute.
• Added: Game Config build window in Unity Editor now supports setting the Name and the Description of the uploaded GameConfig. The underlying API GameConfigBuildUtil.PublishGameConfigArchiveToServerAsync() now also supports setting the name and description.
• Added: Added utility extension Type.HasCustomAttribute() allows checking an attribute presence without allocation, unlike Type.GetCustomAttribute() != null.
• Added: New property in MetaplayCoreOptions for tagging the current ClientPatchVersion and the associated logic for refusing unsupported client patch versions on client login based on the current client patch version requirements in ClientCompatibilitySettings.
• Added: New error type in the session handshake protocol ClientPatchVersionTooOld and the associated client-side MetaplayConnection terminal error state. The default MetaplayClient implementation maps this error into the existing ConnectionLostReason.ClientVersionTooOld which is also used for the case when the client logic version is too old.
• Added: Roslyn analyzers and associated code fixes MP_OD_01 and MP_OD_02 for renaming OrderedDictionary to MetaDictionary.
• Added: RandomPCG now has an overload for NextLong() with a exclusive max parameter.
• Added: The fields of Custom Analytics Contextes are now included in BigQuery Analytics Events. The format of the context fields is described in Analytics Context Representation.
• Added: Collection of various business and performance metrics from the game server. Some of these, mainly DAU, are also sent to the Metaplay portal for future billing purposes.
• Added: New static getters for MetaDuration.Second, MetaDuration.Minute, MetaDuration.Hour and MetaDuration.Day.
• Added: An integration point for adding custom dependency injection services to the AdminAPI, by adding a class that extends the IAdminApiServices interface.
• Added: TryReassignPlayer API to the league integration, which allows a player to be reassigned to a new division within the same season.

• Changed: Database scan jobs now read from the database shards in an interleaved manner, rather than fully scanning one database shard before moving onto the other. This should achieve more efficient utilization of the parallelism provided by multiple database shards.
• Changed: Actor periodic timer invocations no longer pile up without bound when process is paused and instead are limited to max 2x the expected invocation rate. If the server process is paused for debugging or memory dumping, resuming no longer causes a surge of periodic timer calls.
• Changed: DefaultEnvironmentConfigProvider's various path name properties are now correctly virtual, allowing you to override them in a derived class (which automatically will become the active provider thanks to the integration registry system).
• Changed: EntityAskAsync and SubscribeToAsync, will now throw EntityCrashedError instead of UnexpectedEntityAskError if entity crashes while processing some preceding message.
• Changed: SubscribeToAsync will now throw EntityUnreachableError if target entity cannot be reached.
• Changed: UnsubscribeFromAsync will no longer throw TimeoutError if unsubscription cannot be guaranteed by the time limit and instead returns false.
• Changed: The server-side management of LiveOps Events has been moved to a new entity called LiveOpsTimelineManager, to reduce load and responsibilities from GlobalStateManager which previously managed them. This is mostly an SDK-internal change and likely does not affect you. If you send messages directly to GlobalStateManager for managing LiveOps Events, you now need to send those messages to LiveOpsTimelineManager instead.
• Changed: Player mail actions PlayerAddMail, PlayerDeleteMail and PlayerForceDeleteMail now use client/server action base classes rather than setting ModelActionExecuteFlags via attribute to make it easier to understand whether they are client or server actions.
• Changed: game_entity_asks_total and game_entity_ask_errors_total metrics have their message label values changed from <MessageType> to Ask-<MessageType> for EntityAsks.
• Changed: The ASP.NET controllers deriving from Metaplay's base controllers no longer need to pass in the logger or adminApi parameters.
• Changed: Introduce SharedApiBridge and ServerApiBridge to encapsulate the game-specific helpers from GameAdminApiController to make them available in controllers deriving from other controllers, notably from MetaplayWebhookController. The helper methods are available directly on GameAdminApiController but must be invoked via ApiBridge.HelperMethod() in other controllers.
• Changed: The time between app being put into background and session ending is no longer included in PlayerLoginEvent.SessionLengthApprox. This is expected to reduce SessionLengthApprox by about 20 seconds.

• Fixed: In offline mode, the client will now persist the player's state when you explicitly call MetaplayClient.Connection.Reconnect().
• Fixed: The scripting backend setting for dedicated server builds is now parsed correctly for generating the appropriate version of the serializer binary.
• Fixed: When overwriting a player from a different environment, the EntityImportEntityIdRemapper will now remap EntityIds that are not part of the current import entity set or are not persisted in the database to EntityId.None.
• Fixed: Server will now tolerate missing stdin stream even if --Environment:EnableKeyboardInput=false is not given.
• Fixed: Reduce allocations in Client SDK startup.
• Fixed: Serializer generation will no longer fail if a type had a base type or interface in an assembly that was only an indirectly referenced.
• Fixed: Fixed NRE on client if Incident Report with network diagnostics was generated when connected to the offline server.
• Fixed: IMetaplayLifecycleDelegate.OnSessionLost() is now called also when connection is closed with MetaplayConnection.Close().
• Fixed: Metaplay.Core.Json.JsonSerialization now supports deserializing base classes' properties with private setters. This is needed for building game configs from JSON data, because some SDK-defined base classes have properties with private setters yet expect those to be settable via deserialization.
• Fixed: When you overwrite a player that has been marked as developer via the LiveOps Dashboard, the player's developer status is no longer erroneously disabled. Previously, an overwrite would temporarily disable the player's developer status on the server, despite the LiveOps Dashboard still showing the player as a developer.
• Fixed: SDK entity maintenance scan jobs (Entity Schema Migrator and Entity Refresher) now avoid an extraneous unthrottled persistence operation for the target entities. This should reduce resource usage on the server as well as the read-write database during these maintenance jobs.
• Fixed: Broadcasts are no longer filtered only with the player segments that the player was a member of during login. Now broadcast segments are periodically re-evaluated to ensure that if a player enters a segment during a session, broadcasts targeted to that segment will be delivered.

LiveOps Dashboard

Complete List

• Added: Added an optional badge next to the title to MModal.
• Added: Added a new OverviewListItem.asLink() option to the initialization API to make it possible to inject links into the overview lists.
• Added: A new getGameServerHelloSubscriptionOptions() subscription. This provides access to the /hello endpoint of the game server that contains immutable dashboard configuration, like the current environment name and feature flags. The same data is now removed from coreStore.
• Added: Support for generic types in the MInputSingleSelectDropdown component for better type safety.
• Added: Added a new admin action to forcefully update a player's logic version.
• Added: Client redirect settings have been redesigned to support the new client patch version feature.

• Changed: Updated to the latest Node.js LTS version (22.11.0).
• Changed: Upgraded to stricter linting rules for most of the internal modules that go to make up the dashboard. This improves code overall quality. These stricter settings can easily be used for game specific code if required but are disabled by default.
• Changed: The Experiment Detail page has been updated and is now organized into three main tabs:
  • Details Tab: Contains the experiment's details defined in the game configs.
  • Audience & Targeting Tab: Contains details on the experiment's audience and targeting criteria.
  • Audit Log Tab: Displays a log of all changes made to the experiment.
• Changed: The Experiment Detail page overview card has been updated and details of the experiment's target audience have been moved to the Audience & Targeting tab.
• Changed: coreStore.hello has been removed and replaced by the new useStaticInfos() composable in @metaplay/gameServerApi. This composable provides access to the same underlying data, but in a more consistent and easier-to-use way.
• Changed: coreStore.getEnvironmentFamily() has been removed as it was a simple getter for helloData.environmentFamily. Use the new useStaticInfos() composable instead.
• Changed: The replace option has been removed from the addUiComponent() API's layout options as it was ambiguous and rarely used. Call removeUiComponent() followed by addUiComponent() to achieve the same effect.
• Changed: The okButtonDisabled prop for disabling the OK button in modal components (MActionModal, MActionModalButton) has been removed. To disable the OK button, you must now provide a message to the new okButtonDisabledTooltip prop explaining why it’s disabled. This message will be displayed as a tooltip when users hover over the button.
• Changed: The ConfigContentCard experiment search functionality now allows searching by both the experiment name and experiment ID.
• Changed: Improved readability of event payloads on View Audit Log Event page.
• Changed: Removed the red exclamation mark from the player details tabs for players that have incident reports to remove visual clutter.
• Changed: Adjusted disabled button styling to look more distinct from enabled buttons.
• Changed: Improved visibility of clock when using custom DashboardHeaderColorInHex colors.
• Changed: The Settings View has been updated and is now organized into two main tabs:
  • Common Settings Tab: Contains frequently used system settings.
  • Advanced Tab: Contains advanced controls to help you manage your system.

• Fixed: Fixed regression where the clear button on an MInputNumber number component did not work.
• Fixed: Fixed game config contents card not showing a loading state during initial page load.
• Fixed: Fixed a race condition in data loading that would throw an error message in broadcast form when opened with Safari.
• Fixed: Fixed large pop-over dialogs not being always scrollable in mobile Safari.
• Fixed: Fixed large pop-over dialogs sometimes having extra invisible height that forced pages to be scrollable when they should not be.
• Fixed: Fixed tab navigation soft-reloading all components on the page, causing unnecessary data processing and flickering in some elements like buttons.
• Fixed: Fixed a regression in MTabLayout component where the dropdown menu was hidden in mobile view.
• Fixed: Fixed a regression in MTabLayout where the correct tab would not be selected when navigating backwards to a previously viewed page.
• Fixed: Fixed sidebar open/close icon shrinking with very long page names.
• Fixed: Fixed incorrect tooltips on Manage Matchmaker's Bucket Distribution graph which showed how full each bucket was.
• Fixed: Fixed index value on item-card slot of MetaListCard, which was incorrect.
• Fixed: Fixed issue with MInputSingleFile* components where they could have a value that wasn't visible in the UI.
• Fixed: A regression in the LeagueSeasonRankCard that caused it to only access divisions from the lowest rank.
• Fixed: Fixed game config variant preview not showing differences in arrays that contain primitive types.
• Fixed: Matchmaker buckets are now correctly sorted in the Bucket Distribution graph.
• Fixed: The event log cards on the player and guild pages (Latest Player Events and Latest Guild Events) will now reload if the entity crashes or resets and rolls back the event log. Previously, it would either produce errors or display inconsistent events.

Documentation

• New Experiments Documentation: Experiments documentation has been reorganized for easier reading, see Introduction to Experiments to get started. Additionally, a new page Optimizing Experiments offers help to reduce the performance impact of simultaneous experiments.

Complete List

• Added: Meta UI's interactive documentation has new pages about our UI design system and how to use it to create consistent and user-friendly dashboard components.
• Added: New page about client-only hotfixes and patches: Client Patches.
• Added: New section Introduction to Cloud Deployments describes how to interact with Metaplay Cloud hosted game server deployments.
• Added: Dynamic Scaling describes how to dynamically add and remove server nodes, and what are the system's limitations.

Unity 2021.3 Deprecation

Metaplay SDK has deprecated support for Unity 2021.3 as it has reached end-of-life and is no longer supported by Unity. The lowest supported Unity version is now 2022.3. While this release still works with Unity 2021.3, we plan to remove support for it in R32, tentatively scheduled for March 2025.

Still using 2021.3?

If you cannot reasonably upgrade to 2022.3 or later in the near future, please let us know.

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

Helm chart v0.7.0 is recommended for cloud deployments and minimum required version is now v0.6.3.

Migration Steps:

1. Update your CI pipelines for all your environments to use the latest version of the Helm chart.

   When using GitHub Action scripts, make the following change:

   .github/workflows/your-deploy-job.yaml

   jobs:
     ...
     build-and-deploy-server:
       ...
       with:
   -     helm-chart-version: "0.x.y"
   +     helm-chart-version: "0.7.0"

   With other CI systems, apply the following change (or the equivalent in your CI system):

   - export HELM_CHART_VERSION="0.x.y"
   + export HELM_CHART_VERSION="0.7.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.

For All Metaplay Projects

The following core SDK changes affect all Metaplay projects:

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:

   # 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 MetaplayRelease31

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

   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.

For Games With Customized LiveOps Dashboard

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

Install the Correct Node Version

You should ensure that you have Node version 22.11.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.11.0 with Node Version Manager (nvm).
nvm install 22.11.0

# Use the new version.
nvm use 22.11.0

Update the Node version in your project's package.json file to reflect the new requirement:

"engines": {
   "node": "20.x"
   "node": ">=20"
}

Clear Dashboard Dependencies

Migration Steps:

1. 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.

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
   • vue-compat.d.ts
   • index.html

3. Update the compilerOptions in your tsconfig.json file to match the configuration in MetaplaySDK/Frontend/DefaultDashboard. Remove the target, module, and moduleResolution options as they are no longer required.

   {
       "compilerOptions": {
           "composite": true,
           "target": "ESNext", 
           "module": "ESNext", 
           "moduleResolution": "Bundler"
       }
   }

4. Run pnpm install in your 'Dashboard' folder. This recreates all of the above files and folders with the correct dependencies.

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 From coreStore.hello to the useStaticInfos() Composable

Our /hello endpoint is the first thing that the dashboard fetches to access its initial configuration, such as feature flags. We have reorganised and refactored how this data is fetched and stored in the dashboard to make it more consistent and easier to use.

You need to update any possible call sites from coreStore.hello to the new useStaticInfos() composable.

Migration Steps:

1. Import and access the useStaticInfos() composable.

   import { useStaticInfos } from '@metaplay/gameServerApi'
   
   const staticInfos = useStaticInfos()

2. Update coreStore.hello callsites to use the new composable.

   const environmentName = coreStore.hello.environment 
   const environmentName = staticInfos.environmentInfo.environmentName 

3. Remove references to the now unnecessary coreStore.

   import { useCoreStore } from '@metaplay/core'
   
   const coreStore = useCoreStore() 

Here is the updated schema for the data returned by useStaticInfos() for quick reference:

type StaticInfos = {
    projectInfo: {
        projectName: string;
    };
    environmentInfo: {
        environmentName: string;
        environmentFamily: "Local" | "Development" | "Staging" | "Production";
        isProductionEnvironment: boolean;
        grafanaUri: string | null;
        kubernetesNamespace: string | null;
    };
    gameServerInfo: {
        buildNumber: string;
        commitId: string;
    };
    liveOpsDashboardInfo: {
        playerDeletionDefaultDelay: string;
        authConfig: {
            type: string;
            allowAssumeRoles: boolean;
            rolePrefix: string | null;
            logoutUri: string | null;
        };
    };
    featureFlags: {
        pushNotifications: boolean;
        guilds: boolean;
        asyncMatchmaker: boolean;
        web3: boolean;
        playerLeagues: boolean;
        localization: boolean;
        liveOpsEvents: boolean;
        gameTimeSkip: boolean;
        googlePlayInAppPurchaseRefunds: boolean;
        removeIapSubscriptions: boolean;
    };
}

Migrate From coreStore.getEnvironmentFamily() to useStaticInfos()

This function was a simple getter for coreStore.hello.environmentFamily and has been removed in favour of directly accessing the data via the new useStaticInfos() composable that now has the same info at environmentInfo.environmentFamily.

Migration Steps:

1. Import and access the useStaticInfos() composable.

   import { useStaticInfos } from '@metaplay/gameServerApi'
   
   const staticInfos = useStaticInfos()

2. Replace coreStore.getEnvironmentFamily() with staticInfos.environmentInfo.environmentFamily.

   const environmentFamily = coreStore.getEnvironmentFamily() 
   const environmentFamily = staticInfos.environmentInfo.environmentFamily 

   or

   import { getEnvironmentFamily() EnvironmentFamily } from '@metaplay/core'
   
   import { useStaticInfos } from '@metaplay/gameServerApi'
   
   getEnvironmentFamily() === EnvironmentFamily.Local 
   staticInfos.environmentInfo.environmentFamily === 'Local'

3. Remove references to the now unnecessary coreStore.

   import { useCoreStore } from '@metaplay/core'
   
   const coreStore = useCoreStore() 

Update addUiComponent() Calls That Use the replace Option

replace has been removed from the addUiComponent() API's layout options as it was ambiguous and rarely used. Call removeUiComponent() followed by addUiComponent() to achieve the same effect.

Migration Steps:

1. Call removeUiComponent() first and remove the replace option from the addUiComponent() call.

   initializationApi.removeUiComponent('OverviewView', 'GlobalIncidents') 
   initializationApi.addUiComponent(
     'OverviewView',
     { uniqueId: 'CustomGlobalIncidents', vueComponent: async () => await import('./MyOwnIncidentsCard.vue') },
     { position: 'replace', targetId: 'GlobalIncidents' } 
   )

Update Custom Components Targeting Settings View

For custom components targeting the Settings View, update your code to ensure they are assigned to either the System/Common or System/Advanced tab.

Migration Steps:

1. Replace any references to System/Details with one of the following:

   initializationApi.addUiComponent('System/Details', 
   
   initializationApi.addUiComponent('System/Common', 
   
   // Or
   
   initializationApi.addUiComponent('System/Advanced', 

Migration for Metaplay UI Components

The okButtonDisabled prop for disabling the OK button in modal components (MActionModal, MActionModalButton) has been replaced by okButtonDisabledTooltip prop.

Migration Steps:

1. Replace all instances of okButtonDisabled with okButtonDisabledTooltip in your dashboard project.

MActionModal(
- :ok-button-disabled
+ :ok-button-disabled-tooltip="Reason why this button is disabled"
)

MActionModalButton(
- :ok-button-disabled
+ :ok-button-disabled-tooltip="Reason why this button is disabled"
)

MActionModalButton(
- :ok-button-disabled="!customForm.valid"
+ :ok-button-disabled-tooltip="!customForm.valid ? 'Reason why this button is disabled' : undefined"
)

For Games With Custom Dashboard Permissions

If you have customized the role-to-permission table in your Options.*.yaml files, you need to add two additional permissions to the table.

Add New Dashboard Permissions

The following new dashboard admin permissions have been introduced:

• api.players.update_logic_version - Controls who can force update an individual player's logic version.
• api.metrics.view - Controls who can view metrics data.

Migration Steps:

1. Specify which roles should have access to these permissions in your Backend/Server/Config/Options.*.yaml (whichever file you use to configure the access). You can modify the roles as needed.

    AdminApi:
      Permissions:
         ...
         api.players.update_logic_version:       [ game-admin, customer-support-senior, customer-support-agent  ] 
         api.metrics.view:                       [ game-admin                                                   ] 

For Games With Custom ASP.NET Controllers

The following migrations apply to games that have implemented custom ASP.NET controllers. These are generally classes inheriting GameAdminApiController.

Remove Base Controller Constructor Arguments

The Metaplay base controller class constructors no longer need to be passed any arguments.

Migration Steps:

1. Remove the now-unnecessary constructor arguments and call to base class constructor:

   -public MyController(ILogger<MyController> logger, IActorRef adminApi) : base(logger, adminApi)
   +public MyController()

   Optionally, you can now completely remove any fully empty controller constructors:

   -public MyController()
   -{
   -}

For Games With Custom Grafana Dashboards or Prometheus Metric usage

The following changes to Prometheus Metrics may affect your alerting and monitoring stacks:

Update EntityAsk message Label Format

game_entity_asks_total and game_entity_ask_errors_total message label format has changed to clarify the difference of EntityAsks and EntitySubscribes. Asks now produce labels message=Ask-<MessageType> instead of message=<MessageType>. Subscribes continue to produce message=Subscribe-<TargetEntityKind>-<MessageType>. If your metric processing depends on the exact message labels, you need to update your parsing logic.

Migration steps:

1. If you observe a particular Ask rate with game_entity_asks_total{message="FooMessage"}, convert the query to game_entity_asks_total{message="Ask-FooMessage"}.
2. If you observe a particular Ask error rate with game_entity_ask_errors_total{message="FooMessage"}, convert the query to game_entity_ask_errors_total{message="Ask-FooMessage"}.

For Games With Custom Client Connection Error Management

The following changes require integration updates only if your project uses a custom MetaplayClient implementation and therefore handles client connection error states manually.

Handle TerminalError.ClientPatchVersionTooOld

For information on client patch versions see Client Patches.

When clients of unsupported patch versions attempt to connect to the server the connection attempt will result in an error state of TerminalError.ClientPatchVersionTooOld. This should be handled by the game by directing the player to update to the latest released version, similarly to how the error state of TerminalError.LogicVersionMismatch is handled when the advertised supported logic version is greater than the client's.

Migration steps:

1. Add a case in your connection error management code for handling TerminalError.ClientPatchVersionTooOld. Use the existing implementation for handling TerminalError.LogicVersionMismatch.

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 AnalyticsLabel Namespace

The AnalyticsLabel type has been moved from the server-only assembly and Metaplay.Cloud.Analytics namespace to the shared assembly and Metaplay.Core.Analytics namespace.

Migration Steps:

1. If you get errors about AnalyticsLabel not being found, add statement using Metaplay.Core.Analytics;.

Remove Obsolete PlayerClientContext.Update() Call

Manually calling PlayerClientContext.Update() is deprecated and is handled automatically in ClientStore.UpdateLogic.

Migration Steps:

1. If you get a warning of PlayerClientContext.Update() call being obsolete, remove the call.

Update OrderedDictionary to MetaDictionary

To eliminate the name conflict with System.Collections.Generic.OrderedDictionary introduced in .NET 9 the class Metaplay.Core.OrderedDictionary has been renamed to Metaplay.Core.MetaDictionary. For SDK update convenience, the SDK in R31 still contains a migration assistance implementation of Metaplay.Core.OrderedDictionary. This means that your existing code using OrderedDictionary should continue to compile and work, but we strongly recommend updating all uses of it to use MetaDictionary instead, in preparation for updating to .NET 9. The migration assistance helper class OrderedDictionary is marked as Obsolete and any references to the class will yield compiler warnings that you can use to verify that all references have been update.

Note that this change is reflected in the signature of various API entrypoints in the MetaplaySDK code, and this will cause build errors for any integration code that expects the old signature using OrderedDictionary parameters.

Migration Steps:

1. Rename all occurrences of OrderedDictionary to MetaDictionary both in your server and client code.

2. Update any uses of ToOrderedDictionary() to use ToMetaDictionary() instead.

To aid in the renaming, the Metaplay SDK contains a Roslyn code analyzer and an associated code fix that can be used for conveniently carrying out the renaming in your code. The relevant code analyzer diagnostics are MP_OD_01 (use of the OrderedDictionary<,> type) and MP_OD_02 (invocations of the ToOrderedDictionary() method).

Visual Studio 2022 supports batch fixing of analyzer issues via navigating to an occurrence of the issue and clicking on "Fix all occurrences".

The codefixes can also be applied from command line using the dotnet format tool, the invocation is:

dotnet format <workspace> analyzers --diagnostics MP_OD_01 MP_OD_02

The batch execution of code fixes happens in a context of a workspace (solution or project). To carry out the renaming both in server and (Unity) client code you will need to run the operation on both your server solution file and the generated Unity solution file.

Update RandomPCG.NextLong() Overload

A new overload of RandomPCG.NextLong(long maxExclusive) with an exclusive max parameter was added in this release. If you have modified the SDK or implemented a custom conflicting overload, check the compatibility of those methods.

Migration Steps:

1. If you've added a similar custom overload, rename the game-specific overload or use the SDK version if compatible.

Update Analytics Contexts for BigQuery Compatibility

BigQuery analytics sink now support custom Analytics Context classes, and all custom analytics class types are checked at server launch time to be BigQuery-compatible. The check is performed regardless if BigQuery sink is enabled or not.

Migration Steps:

1. If server start fails with an error Unknown analytics event field format in <SomeContextType>, either change the type of the field to become formattable or ignore the field with [BigQueryAnalyticsFormat(BigQueryAnalyticsFormatMode.Ignore)].