Hotfix Release

Release 30.1 is the latest hotfix release for Release 30 and contains a fix for CVE-2024-43483.

If you are on Release 30, you should upgrade to Release 30.1!

Highlights

New Feature: Server Time Skip

You can now skip time into the future on development game servers. This is useful for testing complex event scheduling setups. See the Testing Game Schedules With Time Skipping guide for more information.

Major Improvement: Dashboard Environment Page

The Environment page has been redesigned to display more information about the server cluster, including the status of each node. The page is now organized into tabs, with the runtime options moved into a dedicated tab.

Major Improvement: Multiple Logic Versions

Support for multiple logic versions on the server has been significantly improved. We've added support for using the AddedInVersion attribute on classes, enhanced safety for incompatible logic versions, and introduced visualization in the dashboard.

Changes

Metaplay SDK

• Custom Incident Reports It is now possible to easily create your own custom incident report types. Reporting incidents has also been streamlined. Use MetaplaySDK.IncidentTracker.AddIncidentAndAnalyticsEvent() to report your custom incident or MetaplaySDK.IncidentTracker.AddIncidentWithNetworkReportAndAnalyticsEvent() to include a network report. See Implementing Custom Incident Reports for more information.
• Player Actor Crashed Incident Reports PlayerActor crashes now produce an incident report and an analytics event to help debug and fix these issues.
• Better Player And Guild Search: Player and guild search now prioritize non-bot, non-deleted players and guilds and shorter matching name parts. This should give more relevant results and prevent issues of longer name parts or entity IDs masking shorter name parts.
• Improved Logic Version Handling: We've improved support for having multiple active logic versions. Players are now automatically excluded from Broadcasts and LiveOps Events if they do not support the required logic version. Logic Version incompatible change to the Player Model are now handled more gracefully and prevents the player from losing progress.

Complete List

• Added: Game config spreadsheet parsing now supports deeply nested data within vertical (non-indexed) collections. Structures such as MyList[].OtherList[0].Member are now supported, where previously, at most, 1 level of nesting after the [] was supported.
• Added: Support to localization parsing for comments; any lines or columns starting with // are now ignored.
• Added: Optional property CustomReferencePriceForDashboard, which you can override in your subclass of MetaOfferInfoBase in order to display a price for offers that are not paid with in-app purchases, but with custom means such as soft currencies.
• Added: Player client context operations, such as executing player actions, now check that they are being invoked from the Unity main thread to catch bugs related to accidentally invoking actions from background threads. This check is only enabled in debug builds.
• Added: Automatic population of client build version information during Unity client builds, see: Client Build Version documentation for usage.
• Added: Runtime option fields may now be marked with [EnvironmentVariable()] to add additional environment variables as sources.
• Added: Option of specifying the list of supported logic versions explicitly, rather than only specifying a single range. This can be useful in particular if your logic version numbering scheme doesn't use continuous integers.
• Added: EntitySubscriber and EntitySubscription have SetUserdata<T>() and GetUserdata<T>() to allow storing per-subscription state conveniently.
• Added: Concept of guest credentials "slots" for testing scenarios involving multiple player accounts on a single client build. By default the SDK accepts command line argument --GuestCredentialsSlot for declaring the name of the active slot for the run, the resolving of the active slot can be overridden by a custom implementation of IMetaplayClientConnectionDelegate.GetGuestCredentialsSlotName().
• Added: The per-player debug mode, behind the Enable Debug Mode button on the dashboard's player page, has been extended to allow disabling incident report uploads, in order to debug cases where the uploads themselves appear to worsen connectivity problems. In addition, you can now specify the number of sessions the debug mode should remain active. The existing functionality of enabling game logic consistency checks is still available as an individual parameter under the debug mode.
• Added: Added a new PlayerPropertyLogicVersion to segment based on the player's logic version.
• Added: Added a new SessionForceTerminateReason.LogicVersionUpdated to indicate that the player was kicked due to their logic version being updated mid-session.
• Added: A new set of analyzers to help detect issues with MetaMembers earlier, specifically to detect duplicate, reserved, blocked MetaMembers and MetaMembers in types that are not serialized.
• Added: Added network reports to the SessionPingPongDurationThresholdExceeded incident type and the ConfigFetchFailed incident type.
• Added: Checksum mismatch error reports now contain information if a recent Tick or Action has thrown an unhandled exception. Previously throwing from a Tick or an Action could result in mismatches where client and server states were "bit-exact identical".

• Changed: Toybox 'tar' binary (required when copying files with kubectl cp) is now compiled with Ubuntu 24.04.
• Changed: Client-side IAPManager now logs store purchase failures on the Warning level instead of Info.
• Changed: Player checksum mismatches are now reported as their own incident type instead of as a terminal network error.
• Changed: Increase the tolerance for network failures of Nuget fetches during the docker build to reduce the number of build failures due to temporary Nuget unavailability.
• Changed: MetaDatabase and MetaDbContext types are now in Metaplay.Cloud.Persistence namespace.
• Changed: Update entrypoint binary to be built with Golang 1.22.7. Fixes CVE-2024-34156.
• Changed: Introduce default implementations for MultiplayerEntityClientBase.LogChannelName and MultiplayerEntityClientBase.CreateActiveModelContext() to reduce boilerplate when no customization is needed.
• Changed: Invalid connection handshakes are no longer reported as server errors. This reduces spam when automated bots crawl exposed-to-internet servers.
• Changed: Session resume failures for expired sessions no longer cause an incident report to be generated.
• Changed: MetaDatabaseBase has been removed; MetaDatabase should be used instead.
• Changed: MultiplayerEntityActorBase.TryGetClientPeer() now takes in the EntitySubscription instead of the EntityId.
• Changed: NodeSetConfig.GetMaxNodeCount() is no longer marked as Obsolete.
• Changed: External Dependency Manager for Unity is now required for Android builds.
• Changed: Runtime option Player:NumDebugModeSessions has been removed, as this is now controllable directly from the dashboard when enabling the debug mode.
• Changed: ChannelContextDataBase has been renamed to EntityClientData.
• Changed: Executing a server action on a player now updates that player to the minimum required logic version.
• Changed: Player Mails now update the player to the minimum required logic version of the mail content.
• Changed: The AddedInVersionAttribute is now allowed to be used on classes. An exception of type MetaTypeMissingInLogicVersionSerializationException will be thrown if a type known to be incompatible is serialized.
• Changed: Types or members with logic versions higher than the currently supported logic version range are no longer allowed and will prevent the server from starting.
• Changed: For the game server time skip feature, MetaTime and MetaDuration have been changed to DateTime and TimeSpan in various places. See Miscellaneous API Changes for details on how you may need to update your code.
• Changed: Dropped support for server-internal states from Release 14 (November 2021). If you upgrade directly from Release 14 to Release 30, the state of the current experiments, broadcasts, maintenance mode and the set of players marked as developers will be lost. To keep data, upgrade to any Release between 15 and 29 first.
• Changed: The default localization auto-updating mode has changed. If a localization is updated during an ongoing session, the localization is no longer updated on client to the new version immediately but instead the update is applied on next session start. This can be controlled with IMetaplayLocalizationDelegate.AutoActivateLanguageUpdates setting.
• Changed: Multiplayer Entities added during session start no longer by default prevent session start if client has no game config available. The game config is loaded on background after which the entity becomes available on client. This can be controlled with MultiplayerEntityActorBase.RequireClientHasGameConfigPresentOnSessionStart.

• Fixed: In Dockerfile.server, use correct consistent capitalization for FROM ... AS syntax and remove the redundant target platform definition to silence the related warnings.
• Fixed: The environment config editor now refreshes changes to environment configs from the file before assembly reloads, preventing changes from being lost when editing both environment configs and code files.
• Fixed: The entrypoint binary is now copied from a pre-built source instead of building it in the image. This avoids occasional segmentation faults from go build during cross-architecture docker builds.
• Fixed: The GlobalStateProxy now properly unsubscribes from GlobalStateManager on server shutdown, and a warning is no longer logged.
• Fixed: Dockerfile.server now properly supports cross-compilation of the server and botclient dotnet binaries again.
• Fixed: Reduced false positive SessionCommunicationHanged incident reports (subtype ServerSideSessionPingDurationThresholdExceeded). These false positives would happen when the client went to pause right after resuming a session after a connection loss. Now, the server only reports this incident if the client is not known to be on pause.
• Fixed: Broadcasts no longer enroll players who do not support the content of the broadcast.
• Fixed: LiveOps events no longer enroll players who do not support the content of the event.
• Fixed: The PlayerActor no longer crashes if you've modified the PlayerModel in a logic version incompatible way; rather, the logic version is updated to the minimum required version instead.
• Fixed: Return value of WebApiBridge.JsonCallSync() is now the value returned from the called Javascript method, instead of being always null.
• Fixed: If PlayerActor associated with new entities during session start, this could have caused very short sessions to be reported to analytics and shown in Player event log.

LiveOps Dashboard

• Stricter Code Quality Checks: We have updated ESLint and enabled more rules to help you write safer and more maintainable code. This also paves the way toward ESLint v9 support in the future.
• Prettier Code Formatting: We have added Prettier to the project to enforce consistent code formatting across the dashboard project and its shared modules. Have a look at the IDE Setup guide to get started!

Complete List

• Added: New MPlot and MTimeseriesBarChart components for creating custom data visualizations in the LiveOps Dashboard.
• Added: The matchmaking distribution graph has been rebuilt to support filtering based on bucketing labels and to handle complex matchmaking setups with lots of labeled buckets.
• Added: New MTabLayout component, a tab layout for dashboard pages that provides a way to organize dashboard components into separate tabs.
• Added: Created a new utility module, MetaUtilities, to house utility functions that are shared by other Metaplay modules. This enabled the cleanup and standardization of utility functions as well as the deduplication of some functions that were repeated across modules.
• Added: Permissions support for the MInputSwitch component. You can now set a required permission to control who is allowed to interact with the switch.
• Added: Improved support for logic versions in generated UI.
• Added: Added a new is-targeting-multiple-players property to all meta-generated-* components.
  • Enabling the is-targeting-multiple-players property will show warnings if fields are only supported for a subset of players.
• Added: Added a new logic-version property to all meta-generated-* components.
  • Setting logic-version to a valid value will disable incompatible member and type inputs.
• Added: The MInputSingleSelectRadio component now supports disabling individual options.

• Changed: Improved responsiveness of Player Event streams by allowing interaction with the card even while it is still loading data. Previously, the card would block until all data was loaded, which could cause considerable delays when the event stream was very large.
• Changed: Removed the last references to the b-container component. It is now fully deprecated and has been replaced by the MViewContainer or the Tailwind @tw-container directive to create a responsive container element.
• Changed: MessageAudienceForm and TriggerConditionForm components refactored to the Vue 3 v-model syntax. You may need to update your usage of these components from v-model to model-value and @input to @update:modelValue.
• Changed: Utility functions from Core and MetaUi were moved to the new MetaUtilities module. This may require you to update some of your imports. See the migration guide for details.
• Changed: The MInputSegmentedSwitch component has been renamed to MInputSingleSelectSwitch for consistency with other input components.
• Changed: The MInputSingleSelectSwitch sizes have been updated from sm and md to small and default, respectively.
• Changed: All pages with tabs now use the new MTabLayout component to manage the tab layout. Some pages now have red highlight indicators for tabs with high-priority information.
• Changed: The MInputSwitch component sizes have been updated from xs, sm and md to extraSmall, small and default, respectively.
• Changed: The disabled prop in the MButton, MIconButton and MTextButton components has been replaced by the disabledTooltip prop. To disable the button, set the disabledTooltip prop with an explanation of why the button is disabled.
• Changed: The triggerButtonDisabled prop in the MActionModalButton component has been removed in favor of the triggerButtonDisabledTooltip prop. To disable the trigger button, set the triggerButtonDisabledTooltip prop with an explanation of why the button is disabled.
• Changed: Improved wording of the player incident cards and pages to make them easier to understand. Also restored the alert message that informs users when there have been a large number of incidents within the last 24 hours.
• Changed: Changed dashboard visualization of the error messages for TerminalNetworkError and SessionStartFailed incident types to use the stack trace view.
• changed: Improved the layout, styling and added generics support to the MInputSingleSelectRadio to ensure consistent styling and behavior across the dashboard.
• Changed: The variant prop in MInputSingleSelectRadio now uses primary instead of default as the default variant.
• Changed: The Environment page has been refactored with improvements to layout and styling. The page overview section now provides more detailed information about the current environment.
• Changed: The Clusters tab within the Environment page has been renamed to Servers and refactored to display more information about the nodes running in your environment.
• Changed: The Runtime Options page has been moved to the Environment page and is no longer accessible directly from the sidebar.
• Changed: The list of all available UI placements has now been moved from the uiPlacementApis.ts to uiPlacementList.ts file. Moving forward, all new custom placements should be added to the uiPlacementList.ts file to ensure consistency.

• Fixed: Fixed the brief flash of red striped background when loading the Player Details page.
• Fixed: Fixed the overflow issue with the MInputSingleSelectSwitch component. It now switches to a dropdown on mobile devices for improved usability on smaller screens.
• Fixed: Fixed the MTooltip component sometimes having mouse over trigger area that was too small.
• Fixed: Fixed action buttons on experiment detail view that required a second click to work.
• Fixed: Fixed issue where MetaDuration would not display anything if the duration was less than one second.
• Fixed: Remove support for controlling the number of fraction digits from MInputNumber as it was both broken and unused.

Samples

• Party feature in Idler: To complement the new Introduction To Multiplayer Entities guide, the Idler sample now hosts an implementation of a simple player party system.

Helm chart

• New version of metaplay-loadtest Helm chart: We recommend using metaplay-loadtest Helm chart v0.4.2 if you plan to run bot clients in metaplay-hosted platforms. The metaplay-loadtest Helm chart v0.4.2 adds support for pod affinity rules, which contribute to better pod scheduling and mitigate the risk of resource starvation on nodes on which the game server runs.

Documentation

• Added: Introduction To Multiplayer Entities to demonstrate using the Multiplayer Entities system for building a custom multiplayer feature.
• Added: A page documenting the new Time Skipping feature has been added: Testing Game Schedules With Time Skipping

Complete List

• Added: A page documenting Custom Incident Reports has been added: Implementing Custom Incident Reports

• Changed: Updated the Customizing the LiveOps Dashboard Frontend guide to include more information on the suggested IDE setup and available commands.
• Changed: Updated the Customizing the LiveOps Dashboard Frontend guide. It now includes an up-to-date list of all available UiPlacements and updated instructions on how to use them to customize the dashboard.

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 R31, tentatively scheduled for December 2024.

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

The Metaplay SDK now requires Helm chart v0.6.3 for any cloud deployments. This has not changed from Release 29, if you are already on Helm Chart v0.6.3, then no action is required.

Migration Steps:

1. Update your CI pipelines for all your environments to use version 0.6.3 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.6.3"

   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.6.3"

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 it 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 migration steps for features you are not using in your project.

For All Metaplay Projects

The following core SDK changes affect all Metaplay projects:

Add the Metaplay.CodeAnalyzers.Shared

We've created a new set of code analyzers to help catch serialization errors earlier.

Migration Steps:

1. Open the MyGame-Server solution
2. Right-click on the Metaplay folder
3. Use the Add > Existing Project menu item to add MetaplaySDK\Backend\CodeAnalyzers.Shared\Metaplay.CodeAnalyzers.Shared.csproj
4. Add the analyzer reference to the Server.csproj and SharedCode.csproj, insert the following snippet next to the other ProjectReference entries.

<ProjectReference Include="$(MetaplayServerPath)\CodeAnalyzers.Shared\Metaplay.CodeAnalyzers.Shared.csproj">
    <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
    <OutputItemType>Analyzer</OutputItemType>
</ProjectReference>

Update Your CI Jobs

We've updated our CI job templates to be much better at reporting errors, for example when the deployment fails due to the server not starting due to a misconfiguration. You should upgrade to the latest revision to get the benefits.

Migration Steps:

1. Go to https://portal.metaplay.dev and find the CI instructions from Projects > View Project > View Environment > Deploy Server.
2. Copy-paste the template based on the CI system that you're using on top of your existing job definition (eg, .github/workflows/build-deploy-server-<environment>.yaml for those using Github Actions).
3. Apply any modifications that you've done to customize the jobs for your project.

Apply Database Schema Migrations

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

You might need to apply some of the steps in Miscellaneus API Changes before you can run the database schema migrations.

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 MetaplayReleaseXX

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.

Possibly long migrations

Note: Release 30 introduces a new index to the player and guild search tables and the migrations can take up to several minutes on large databases.

For Games Targeting Android

The following core SDK changes affect projects that have an Android client.

Install External Dependency Manager for Unity (EDM4U)

MetaplaySDK depends on External Dependencies on Android for Maven packages. You will need to ensure EDM4U is installed to the Unity Project.

Migration steps:

1. Check if EDM4U is already installed by opening Menu > Assets > External Dependency Manager. If this menu exists, EDM4U is already successfully installed.
2. If EDM4U is NOT installed, install it using the instructions in Using the External Dependency Manager for Unity on Android.

For Games With Customized LiveOps Dashboard

The following LiveOps Dashboard changes affect projects that have a customized dashboard:

Install the Correct Node Version

You should ensure that you have Node version 20.18.0 (the latest 20.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 20.18.0 with Node Version Manager (nvm).
nvm install 20.18.0

# Use the new version.
nvm use 20.18.0

Clear Dashboard Dependencies And Remove Outdated Files and Directories

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. Remove any files that Node has cached in your repository. This will lead to a fresh install of all dependencies.

   • Remove all node_modules directories and their contents. This clears any currently installed dependencies. One way to do this is to run git clean -fdx ':(glob)**/node_modules/*' from the root of your repository.
   • Remove all dist directories and their contents. This clears any previously built files. One way to do this is to run git clean -fdx ':(glob)**/dist/*' from the root of your repository.
   • Delete the pnpm-lock.yaml file from the root of your repository. This clears the cached dependency versions.

2. Old project and configuration files often accumulate in repositories over time. You should remove all of the following files and directories from your dashboard directory if they exist.

   • metaplay_temporary_copy_of_core_tests
   • src\vue-compat.d.ts
   • .eslintrc.cjs
   • cypress.config.ts
   • postcss.config.cjs
   • tailwind.config.cjs

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 directory as the source of truth for these files.

Migration Steps:

1. Copy the following files to your dashboard root directory:

   • .prettierignore
   • eslint.config.js
   • postcss.config.js
   • prettier.config.js
   • tailwind.config.js

2. Optional: This release includes new, stricter code formatting results that are applied automatically by default. This can cause issues in a large codebase where the number of changes can be overwhelming. While we strongly recommend working through these issues and addressing each one, you may decide to opt out of the automatic code formatting introduced in this release. You can do this by changing the first line of your eslint.config.js:

   import MetaplayEslintConfig from '@metaplay/eslint-config/recommended'
   import MetaplayEslintConfig from '@metaplay/eslint-config'

3. Copy and overwrite the following files

   • tsconfig.app.json
   • tsconfig.node.json

4. 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".

5. Run pnpm install in your dashboard directory. This installs all of the correct dependencies.

Remove Deprecated Components

As part of the ongoing effort to migrate away from Bootstrap, we have removed the following components in favor of the new MetaUiNext components.

• b-container is replaced by MViewContainer or the Tailwind @tw-container directive.

Unfortunately, the migration is not automatic, so you will need to manually replace the removed components with the new ones in your dashboard project.

Migration Steps:

1. Find all instances of the b-container component in your dashboard project.

2. Replace b-container with the MViewContainer component for root-level elements or use the Tailwind @tw-container directive for child-level elements that previously used b-container, as shown below:

   // For root-level elements
   b-container( 
   MViewContainer( 
   ...
   )
   
   import { MViewContainer } from '@metaplay/meta-ui-next'

   // Or

   // For child-level elements
   b-container( 
   div(class="@tw-container"
   ...
   )

Fix ESLint Errors and Warnings

We have updated ESLint and enabled more rules to help you write safer and more maintainable code. Run ESLint to find and fix any new issues.

Migration Steps:

1. Run pnpm lint in your dashboard directory. This will show you all ESLint errors and warnings.

2. Either fix the issues or selectively ignore them with // eslint-disable-next-line RULE_NAME_HERE comments.

3. If the number of issues is overwhelming, you may choose to disable the new formatting rules. See section 2 of Update the LiveOps Dashboard Project Files for how to do this.

New MetaUtilities Module

We have moved a number of utility functions from Core and MetaUi to a new MetaUtilities module. If you are using any of these functions in your custom dashboard code you will need to update your imports.

The following functions were moved to MetaUtilities:

• abbreviateNumber(x: number) - Abbreviates an arbitrary number into a short display string.
• maybePluralPrefixString(count: number, singular: string, plural: string) - Generates prefix text for potentially pluralized text.
• maybePluralString(count: number, singular: string, plural: string) - Generates a humanized string that pluralizes a word if needed.
• toOrdinalString(n: number) - Returns a string with an ordinal appended to the given number.
• camelCaseToSentenceCase(input: string) - Convert a camelCase string to sentence case.
• camelCaseToTitleCase(input: string) - Convert a camelCase string to title case.
• sentenceCaseToKebabCase(input: string) - Converts a sentence case string to a kebab case string.
• stringToSentenceCase(input: string) - Convert a string to sentence case.
• stringToTitleCase(input: string) - Convert a string to title case.
• makeIntoUniqueKey(input: string) - Generates guaranteed locally unique keys.

Migration Steps:

1. Update affected imports in your .ts and .vue source files.

   - import { abbreviateNumber } from '@metaplay/meta-ui'
   + import { abbreviateNumber } from '@metaplay/meta-utilities'

2. Run pnpm build from your dashboard directory to verify that all imports have been correctly updated.

MInput Component Migrations

The MInputSegmentedSwitch component has been renamed to MInputSingleSelectSwitch and sizes updated. For more details check our meta-ui docs. The MInputSwitch component sizes have been updated from xs, sm and md to extraSmall, small and default, respectively. The disabled prop in the MButton,MIconButton and MTextButton components has been replaced by the disabledTooltip prop. The triggerButtonDisabled prop in the MActionModalButton component has been removed in favor of the triggerButtonDisabledTooltip prop.

Migration Steps:

1. Replace MInputSegmentedSwitch with MInputSingleSelectSwitch Search and replace all instances of the MInputSegmentedSwitch with the MInputSingleSelectSwitch component.

   MInputSegmentedSwitch( 
   MInputSingleSelectSwitch( 
       size="sm"
       size="small"
   ...
   )

2. Update Size Prop in MInputSwitch Search and replace all instances of the MInputSwitch component in your dashboard project that have sizes set to xs, sm or md, with extraSmall, small or default, respectively. For example:

   MInputSwitch(
     size="sm"
     size="small"
     ...
   )

3. Replace disabled Prop in Button Components Search for all instances of the MButton, MIconButton and MTextButton components in your dashboard project that have the disabled prop set and replace the disabled prop with the disabledTooltip prop as follows:

   MButton(
     :disabled="disabledFlag"
     :disabled-tooltip="disabledFlag ? 'Reason for disabling.' : undefined"
   ...
   )

4. Replace triggerButtonDisabled Prop in MActionModalButton Component Search and replace all instances of the MActionModalButton component in your dashboard project that have the triggerButtonDisabled prop set with the triggerButtonDisabledTooltip prop.

   MActionModalButton(
     :trigger-button-disabled="disabledFlag"
     :trigger-button-disabled-tooltip="disabledFlag ? 'Reason for disabling.' : undefined"
     ...
   )

For Games With Custom Dashboard Permissions

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

Add New Dashboard Permissions

The following new dashboard admin permissions have been introduced:

• api.system.view_cluster_nodes - Controls who can view the cluster nodes in environment page.
• api.game_time_offset.edit - Controls who can use the server time skip development feature.

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.system.view_cluster_nodes:       [ game-admin, game-viewer                          ] 
         api.game_time_offset.edit:           [ game-admin                                       ] 

For Games With Custom UiPlacements

If you have added custom UiPlacements to your dashboard, you need to move them from the uiPlacementApi.ts to the uiPlacementList.ts file.

Move Custom UiPlacements

Migration steps:

1. Copy and remove the custom placements from the uiPlacementApi.ts file.
2. Add the custom placements to the uiPlacementList in the uiPlacementList.ts file.

   // uiPlacementApi.ts
   const const uiPlacementList = [ 
       ...
       // Custom UiPlacements
       'Players/Details/CustomPlacement', 
       ...

   // uiPlacementList.ts
   const uiPlacementList = [ 
       ...
       // Custom UiPlacements
       'Players/Details/CustomPlacement', 
       ...
   ]

For Games Using UdpPassthrough

If you are running UdpPassthrough in direct Public IP mode, i.e. bypassing loadbalancers, defining METAPLAY_SUPPORT_PUBLIC_IP_UDP_PASSTHROUGH is no longer required.

Remove METAPLAY_SUPPORT_PUBLIC_IP_UDP_PASSTHROUGH define symbol

To ensure smooth MetaplaySDK updates, experimental feature flags should be cleaned after the features graduate and become incorporated into vanilla SDK.

Migration steps:

1. In Directory.Build.targets remove the symbol:

   Directory.Build.targets

   - <DefineConstants>$(DefineConstants);METAPLAY_SUPPORT_PUBLIC_IP_UDP_PASSTHROUGH</DefineConstants>

For Games Specifying Server Option Player:NumDebugModeSessions

If you have specified a value for option Player:NumDebugModeSessions in your Options.*.yaml files, you need to remove it.

Remove the Player:NumDebugModeSessions Option

The number of sessions that the debug mode remains active is now controlled directly from the dashboard, in the Enable Debug Mode form on the player page. The old server option for it has been removed.

Migration steps:

1. In the options file, such as Options.base.yaml, remove the NumDebugModeSessions option in the Player section.

   Options.base.yaml

    Player:
      NumDebugModeSessions: 5

For Games Specifying Server Options in the PlayerIncident section

If you have specified a value for any of the upload percentage options under PlayerIncident options in your Options.*.yaml files, you need to migrate them to the new dictionary format.

Migrate the upload percentage options

The upload percentage for Player Incidents is now set through a dictionary to support custom Player Incident types. This affects options PlayerIncident:UploadPercentageTerminalNetworkError, PlayerIncident:UploadPercentageUnhandledExceptionError, PlayerIncident:UploadPercentageSessionCommunicationHanged, PlayerIncident:UploadPercentageSessionStartFailed and PlayerIncident:UploadPercentageCompanyIdLoginError.

Migration steps:

1. In the options file, such as Options.base.yaml, replace the UploadPercentage* options in the PlayerIncident section with dictionary entries in UploadPercentagesPerIncidentType. The dictionary keys should match the C# type names.

   Options.base.yaml

   PlayerIncident:
     UploadPercentageTerminalNetworkError: 50
     UploadPercentagesPerIncidentType: 
       "TerminalNetworkError": 50

For Games with Localizations

If you update and publish localizations throught the Dashboard, you need to update the client configuration if you want to keep the existing client-side behavior.

Set the desired Auto-update mode on client

The IMetaplayLocalizationDelegate.AutoActivateLanguageUpdates has been changed to default to false. This means that if a localization is updated during a session, the client will not use the new localization until the start of the new session. The previous default value of true means the client would have switched to the new localization version immediately after downloading the new localization data.

To keep the previous default, automatic hot-loading, you need to update the your LocalizationDelegate.

Migration steps:

1. If you do not already have a LocalizationDelegate, define a new class in the client code.

   GameLocalizationDelegate.cs

   class GameLocalizationDelegate : DefaultMetaplayLocalizationDelegate
   { 
   } 

   And add it as the localization delegate in SDK init.

   MetaplayClient.Initialize(new MetaplayClientOptions
   {
       ...
       LocalizationDelegate = new GameLocalizationDelegate(), 
   };

2. In your LocalizationDelegate, override the AutoActivateLanguageUpdates property to return true.

   GameLocalizationDelegate.cs

   class GameLocalizationDelegate : DefaultMetaplayLocalizationDelegate
   {
       public override bool AutoActivateLanguageUpdates => true; 
   }

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.

Changes from MetaTime to DateTime

With the server time skip feature, we have changed some SDK-side usage of MetaTime to DateTime to avoid unwanted effects during time skips. Similarly, some MetaDuration instances have been changed to TimeSpan. These changes affect some public APIs.

Migration Steps:

1. If you pass ConnectionConfig in MetaplayClientOptions when calling MetaplayClient.Initialize(), update the MetaDurations to TimeSpans. For example:

   ApplicationStateManager.cs

   MetaplayClient.Initialize(new MetaplayClientOptions
   {
       ...
   
       ConnectionConfig = new ConnectionConfig
       {
           ConnectTimeout = MetaDuration.FromSeconds(40), 
           ConnectTimeout = TimeSpan.FromSeconds(40), 
       },
   }

2. When calling MetaplaySDK.OnApplicationAboutToBePaused(), pass in a TimeSpan instead of MetaDuration:

   MetaplaySDK.OnApplicationAboutToBePaused("Showing an ad", MetaDuration.FromSeconds(180)); 
   MetaplaySDK.OnApplicationAboutToBePaused("Showing an ad", TimeSpan.FromSeconds(180)); 

3. When accessing MetaplaySDK's pause-related static properties, use DateTime and TimeSpan instead of MetaTime and MetaDuration.

   MetaTime pauseBeganAt = MetaplaySDK.ApplicationLastPauseBeganAt;
   MetaDuration pauseDuration = MetaplaySDK.ApplicationLastPauseDuration;
   DateTime pauseBeganAt = MetaplaySDK.ApplicationLastPauseBeganAt;
   TimeSpan pauseDuration = MetaplaySDK.ApplicationLastPauseDuration;

   ⚠️ Heads up

   If your existing code used the Milliseconds property of MetaDuration, make sure to change that to the TotalMilliseconds property of TimeSpan! TimeSpan also has a Milliseconds property, but with a different meaning: it is only the milliseconds component, instead of the total milliseconds as in MetaDuration. This discrepancy won't be caught by the compiler on its own, so after changing MetaDurations to TimeSpans, you should use your IDE to find all references to TimeSpan.Milliseconds and review those.

Remove references to GuildModelBase.IsNameSearchValid

GuildModelBase.IsNameSearchValid has been removed in favor of the new GuildModelBase.SearchVersion, which automatically fulfills the same function.

Migration steps:

1. Remove references to GuildModelBase.IsNameSearchValid.

Update references to MetaDatabase, MetaDbContext and QueryPriority.

MetaDatabase and MetaDbContext types have been moved into Metaplay.Cloud.Persistence namespace.

Migration steps:

1. In each file using MetaDatabase, MetaDbContext or QueryPriority, add

using Metaplay.Cloud.Persistence; 

Remove references to PlayerSessionParamsBase.IsDryRun

Dry-run mode has been removed from session start protocol. All references to it should be removed.

Migration steps:

1. If you have a type inheriting PlayerSessionParamsBase, do not pass in isDryRun argument to base constructor.

2. Remove references to InternalSessionStartNewRequest.IsDryRun.

Replace references to ChannelContextData with EntityClientData.

The ChannelContextData has been removed and replaced with EntityClientData. If you have custom Multiplayer Entities and you supply the client a custom ChannelContextData in via MultiplayerEntityActorBase.CreateClientSessionStartChannelContext(), you need to update the API calls to the new naming.

Migration steps:

1. Change the base class of your ChannelContextData to EntityClientData:

   MyContextData.cs

   public class MyChannelContextData : ChannelContextDataBase
   public class MyEntityClientData : EntityClientData
   {
       ...
   }

2. In Multiplayer Entity Actor, replace the CreateClientSessionStartChannelContext() hook with CreateClientSessionStartEntityClientData()

   MyActor.cs

   protected override ChannelContextDataBase CreateClientSessionStartChannelContext(...) 
   protected override EntityClientData CreateClientSessionStartEntityClientData(...) 
   {
       return new MyChannelContextData(...); 
       return new MyEntityClientData(...); 
   }

3. Replace all uses of EntityInitialState.ContextData with EntityInitialState.ClientData:

   MyClient.cs

   void DoSomethingWithState(EntityInitialState state)
   {
       MyChannelContextData clientData = (MyChannelContextData)state.ContextData; 
       MyEntityClientData clientData = (MyEntityClientData)state.ClientData; 
   
       // do something with clientData.Slot or other fields.
   }

Changes to session start negotiation.

SessionProtocol.SessionStartSuccess.ActiveExperiments been moved into InitialPlayerState.ActiveExperiments. ClientSessionStartResources.GameConfigs no longer has specialized configs per slot.

Migration steps:

1. If you have a custom connection delegate, update OnSessionStarted() signature.

   class MyConnectionDelegate
   {
       public override void OnSessionStarted(ClientSessionStartResources startResources) 
       public override void OnSessionStarted(SessionProtocol.SessionStartSuccess sessionStart, ClientSessionStartResources startResources) 
       {
           ...
       }
   }

2. In each call site for ClientSessionStartResources.GameConfigs[ClientSlotCore.Player], (i.e. Getting the player's game config), use the GetConfigForPlayer() method:

   public override void OnSessionStarted(SessionProtocol.SessionStartSuccess sessionStart, ClientSessionStartResources startResources)
   {
       var something = Connection.SessionStartResources.GameConfigs[ClientSlotCore.Player]; 
       var something = Connection.SessionStartResources.GetConfigForPlayer(sessionStart.PlayerState); 
   }

3. In each call site for ClientSessionStartResources.GameConfigs for non-player entities, use the TryGetConfigForEntity() method:

   EntityInitialState initialState = ...;
   var something = Connection.SessionStartResources.GameConfigs[myslot]; 
   var something = Connection.SessionStartResources.TryGetConfigForEntity(initialState.State); 

   Note that TryGetConfigForEntity() may return a null value if the Entity of the EntityInitialState is added during an ongoing session, or if Entity is added on Session Start but Entity Actor's MultiplayerEntityActorBase.EntityInitialStateRequireClientHasGameConfigPresentOnSessionStart => false.

4. In each file using SessionStartSuccess.ActiveExperiments, update access path:

   public override void OnSessionStarted(SessionProtocol.SessionStartSuccess sessionStart, ClientSessionStartResources startResources)
   {
       DoSomething(sessionStart.ActiveExperiments); 
       DoSomething(sessionStart.PlayerState.ActiveExperiments); 
   }

Release 30.1

Released on: October 17th, 2024

Changes

• Changed: Updated Microsoft.Extensions.Caching.Memory to v8.0.1 to fix CVE-2024-43483.
• Changed: Changed the default metaplay-loadtest Helm chart version to v0.4.2.

For All Games

This issue affects all Metaplay server instances.

Migration Guide

The CVE-2024-43483 vulnerability affects the System.Security.Cryptography.Cose, System.IO.Packaging, and Microsoft.Extensions.Caching.Memory packages.

Migration Steps:

1. Restore NuGet Packages in the Backend folder.
   • With the Dotnet commandline tool, you can do this using the following command: dotnet restore.
   • Alternatively your IDE might also be able to help.
2. Fetch all included packages from your Solution file.
   • Ensure that transitively included packages are fetched as well.
   • With the Dotnet commandline tool, you can do this using the following command: dotnet list package --include-transitive.
   • Alternatively your IDE might also be able to help.
3. Verify that System.Security.Cryptography.Cose, System.IO.Packaging, and Microsoft.Extensions.Caching.Memory are not included in the listed package or that they are at minimum on version 8.0.1.
   • If the above packages are on version 8.0.0, then an explicit depedency should be added with version v8.0.1.