Latest release

Release 29.4 is the latest hotfix release for Release 29.

Critical update available!

Release 29.2 contains fixes for two issues related to use of Unity's XXHash3 starting in Release 29:

• Unity's XXHash3 crashes on 32-bit Android and other ARMv7 devices.
• Unity's XXHash3 produces incorrect results for specific buffer sizes, triggering spurious checksum mismatches.

Both of these were regressions in Release 29 as we started using Unity's new Burst-optimized XXHash3 implementation. The issues are also present in Release 29.1.

If you are on Release 29 or 29.1, you should immediately upgrade to Release 29.4!

Highlights

New Feature: Multiple Leagues Support

You can now run multiple leagues simultaneously, each with its own rules, participants, and settings. See the Advanced Leagues Customization guide for more information.

Major Improvement: Automated LiveOps Dashboard Tests

We have migrated our tests to use the Playwright test runner. This setup is now also available for your game-specific dashboard tests. Playwright is significantly faster than the previous Cypress-based runner, allowing us to increase the built-in test coverage. Check out the Introduction to Automated Testing to get started with your own tests.

New Feature: Interactive MetaUI Documentation

Our component library documentation is now publicly accessible both locally and on the web. Browse through a wide range of components and learn how to use them in your custom dashboard. Start exploring the Metaplay UI overview page for more information.

Changes

Metaplay SDK

• Faster docker builds: Docker builds are now approximately 2 minutes faster. The speedup is due to building the source project once (with Release configuration) and using that for generating serializers and validating project configuration.
• Force clients to update to the latest game config: Added a "kick connected clients" flag for the game config publish operation. This will result in the immediate session termination of currently connected clients, forcing them to reconnect and update to the newly published game config.
• Faster checksum hashing: Switched to use highly-optimized platform-provided XXHash3 libraries in Unity and .NET, significantly speeding up checksum computations. Hashing performance is improved by ~3.6x in device builds, ~5-6x on the server, and ~19x in the Unity Editor.
• More EntityKind values: EntityKind values up to 1024 are now supported (up from the previous maximum of 64).
• Services initialization refactoring: The Metaplay SDK now uses dependency injection for initializing and configuring various systems and services, replacing the use of static instance variables. This change allows for more flexible instantiation of SDK systems for testing needs in the future.

Complete List

• Added: KeyManagerActor that supports creating signature JWTs for outgoing requests.
• Added: Message dispatcher listeners added with AddListener() can be given a label argument to allow removing all listeners with a specific label with RemoveListenersWithLabel().
• Added: RuntimeOptionsBase.GetDependencyAsync() which can be used in runtime options OnLoadedAsync() to better support dependencies between runtime options classes.
• Added: New MetaReceiveActor._cancelTimers helper that can be given to Akka.NET's Context.System.Scheduler.ScheduleTellOnce() and Context.System.Scheduler.ScheduleTellRepeatedly() to automatically cancel the timers on entity shutdown.
• Added: The Environment Configs Editor in Unity now supports batch importing all environment configs of a project from the Developer Portal.
• Added: New metric dotnet_runtime_info with labels for the .NET version and runtime. The runtime information is also logged when the server is started.
• Added: BotClientBase now supports making fake in-app purchases. You can use the StartFakeInAppPurchase(InAppProductId) method for static IAPs. For dynamic-content IAPs, invoke the appropriate feature-specific action for preparing the dynamic content (e.g., PlayerPreparePurchaseMetaOffer for MetaOffers), and BotClientBase will automatically make the purchase after the server has confirmed the dynamic content.
• Added: Meta deserialization can now use the constructor to create the object using a subset of the properties. All other properties are set using the property setter.
• Added: The GameConfigBuildWindow now supports abstract types, integers, floats, incremental builds, and constructor-based serialization.
• Added: A new utility to render MetaSerializable types using UITK in Unity, see MetaGeneratedEditorUI for more info.
• Added: New TerminalError.ProjectNameMismatchError connection state for when the client and server do not have the same project name.
• Added: A new metric game_player_actions_time tracking the duration of each action's execution.
• Added: New override RuntimeOptionsBase.OnLoadedAsync(RuntimeOptionsRegistry) for accessing the existing registry for dependent options via GetDependencyAsync().
• Added: Application.AddServices() for introducing application-specific services to the service collection. This replaces Application.PreinitializeAsync() that was previously used for initializing services statically.
• Added: RuntimeEnvironmentInfo container for application runtime configuration that was previously owned by RuntimeOptionsRegistry.
• Added: EphemeralMultiplayerEntityActorBase to complement PersistedMultiplayerEntityActorBase. Ephemeral entities behave identically to the persisted variants, except their state is not stored in the database. Instead, on each actor wakeup, they start with no state.

• Changed: Upgraded EFCore libraries to v8.0.7.
• Changed: The Unity Client SDK now depends on com.unity.collections v1.4.0, which is required to use Unity's XXHash3.
• Changed: MetaSerialization.ResolveMetaRefs() now throws InvalidOperationException instead of MetaRefResolveError when it encounters an unresolvable MetaRef. Accordingly, the MetaRefResolveError type has been removed. The dedicated exception type was removed because the SDK no longer needs it, due to improvements in MetaRef validation at game config build time.
• Changed: MetaSerialization.ResolveMetaRefs() now takes the object by value instead of as ref. Due to a change in Metaplay release 28, MetaSerialization.ResolveMetaRefs() no longer reassigns the identities of the objects in the object tree but merely in-place mutates the MetaRefs.
• Changed: EntityAsks to entities with no matching EntityAskHandler fail with NoHandlerForEntityAsk exception instead of timing out.
• Changed: DynamicEnum no longer supports negative id values.
• Changed: Bots port scanning for SMTP (Simple Mail Transfer Protocol) or FTP servers connecting to the game server no longer cause "Got malformed first packet" errors. SMTP and FTP handshakes are detected and ignored.
• Changed: The update-cloudcore-versions.sh script is now embedded in the Dockerfile.server.
• Changed: By default, the player deletion sweep time is now randomized for each project/environment pair to avoid all deployments performing the operation at a synchronized time.
• Changed: Removed the obsolete step for migrating experiment-related samples from GlobalStateManager to StatsCollectorManager.
• Changed: The server now warns about the GC not being in server mode at start. Previously, the mode was only logged on server start without clear indication of what is desired.
• Changed: MetaplaySDK.EditorHookOnExitingPlayMode has been removed. It was previously used for flushing the network thread log buffer associated with a current server connection on editor playmode exit. The same effect is now achieved by explicitly closing any existing connection in MetaplaySDK.OnApplicationQuit.
• Changed: MetaplaySDK.ExitRequestedCallback has been removed. Automatic MetaplayClient deinitialization on editor playmode exit is now implemented within the default MetaplayClient implementation.
• Changed: Removed TaggedWireSerializer.GetWireType(Type). The type registry to use for finding MetaSerializable types must now be explicitly passed in (use MetaSerializerTypeRegistry.TypeInfo.Specs in most cases).
• Changed: Moved deserialization constructor parameter default values from MetaSerializerTypeInfo.ConstructorParameterValues into MetaSerializableType.ConstructorParameterValues.
• Changed: The runtime options are no longer printed at server start-up when running locally. Press the 'O' key to print them as needed.
• Changed: The server now starts about 1.2 seconds faster when started locally.
• Changed: Removed the RUN_TESTS flag for Dockerfile.server as it's no longer needed.
• Changed: Removed MetaDelay unit tests that became flaky under extreme CPU starvation, as in CI environments.
• Changed: Meta serialized types using constructor-based deserialization now more loosely match the parameter name to a MetaMember by ignoring underscores.
• Changed: Menu Items that are only supposed to run once are now hidden after being run.
• Changed: Environment configs are now stored under ProjectSettings/Metaplay by default instead of Assets/Resources/Metaplay/Editor. The file is automatically moved to the new location when Unity is opened.
• Changed: PlayerModel.CurrentTick and other model timeline tick counters have been changed from int to long. This change supports custom tests that run simulated gameplay over a very long time span without resetting the tick counter. The behavior of the tick counter during normal gameplay has not been changed and is still reset at the start of each game session.
• Changed: Specifying GameMagic in MetaplayCore constructor is now optional.
• Changed: ClusterConfig.NodeSets has been hidden to prevent indexing into the NodeSets, which is error-prone. To enumerate all nodesets, use the EnumerateNodeSets() method.
• Changed: ShardingStrategies.CreateService() has been removed and replaced with CreateStaticService() and CreateDynamicService(). See the migration guide for details.
• Changed: The Unity SDK now automatically detects whether Firebase Messaging was installed using the .unitypackage file instead of the package manager.
• Changed: In MetaplayController, AskEntityAsync() has been renamed to EntityAskAsync() for consistency with the equivalent method in EntityActor. The old method still exists for the time being but is marked [Obsolete].
• Changed: MetaplayCore.Initialize() has been rewritten to internally use a lightweight dependency injection system conceptually compatible with the .NET dependency injection framework. Core initialization by the server application no longer uses this method in favor of configuring the services into the .NET service collection via IServiceCollection.AddMetaplayCore().
• Changed: Various Metaplay core and server services have been migrated from internally storing their state in static context to being instance-based and accessible to dependent systems via dependency injection. To ease the migration effort, access to the systems via a static singleton getter is retained and implemented by a lookup from the MetaplayServices static service locator.
• Changed: MetaplayCore.Initialize() now takes care of initializing the MetaSerialization system as well, removing the need for initializing serialization separately.
• Changed: The server and botclient applications now use the .NET Generic Host for managing the lifetime of the application. The application payload is split into .NET Hosted Services managed by the host.
• Changed: RuntimeOptionsRegistry is now pre-initialized early during the application configuration for the ability to read startup options prior to starting the application host.
• Changed: The user-side shared code (typically Assets/SharedCode/) and SDK shared code (MetaplaySDK/Client/) must now exist in different client-side assemblies. The SDK enforces this when running in the Unity Editor. For all new projects, and most existing projects, nothing is changed, since this is already the case in normal SDK installations.
• Changed: ForceFullDebugConfigForBots is now only enabled by default for locally run bots.
• Changed: The EntityConfig.EntityActorType and PersistedEntityConfig.PersistedPayloadType now take an EntityId parameter.
• Changed: Removed SupportedSchemaVersions helpers in PersistedEntityConfig. They are now found in PersistedEntityActor.
• Changed: Renamed IEntityAsker to IEntityMessagingApi.
• Changed: PlayerActorBase.OnAssociatedEntityRefusalAsync() no longer is given the redundant EntityId playerId parameter.

• Fixed: The Prometheus metrics exporter now uses ASP.NET and therefore no longer requires custom permissions to open the HTTP port on Windows.
• Fixed: Silenced the ASP.NET warnings about Data Protection key storage as we're not using it. Added a custom DataProtectionProvider that throws to ensure any accidental usage is noticed.
• Fixed: Fixed Unity client getting stuck in connection state if the session's entities changed during login handshake and a new game config needed to be updated.
• Fixed: MetaSerialization now supports null DynamicEnums. It used to throw NullReferenceException.
• Fixed: Messages scheduled with EntityActor.StartPeriodicTimer() did not get canceled if the actor crashed, which caused dead letter warnings.
• Fixed: Fixed Entity Association refusal handler (PlayerActor.OnAssociatedEntityRefusalAsync) not run for associations marked to end automatically on session end (PlayerActorBase.AddEntityAssociation(..., removeOnSessionEnd: true)) if the initial entity rejects session with resource correction.
• Fixed: OrderedDictionary<TKey, TValue> used via the non-generic IDictionary interface now allows a null key or value when the respective TKey or TValue type is a Nullable<> type. Previously, it threw an ArgumentException on null keys and values unless the type parameter was a reference type.
• Fixed: Reduced the number of unnecessary database queries for entity event log timestamps (metrics label GetEventLogTimestamp), which could occur when a player sends a large number of PlayerActions in a single batch.
• Fixed: JSON.net's type name formatting in the AdminAPI now includes the full type name, rather than a partial simplified type name.
• Fixed: The integration registry now supports using private parameterless constructors.
• Fixed: The player's league state is now wiped when importing a player to avoid referring to another environment's league.

LiveOps Dashboard

• Server errors page renamed to server messages: The new page now includes both game server errors and telemetry messages sent from the Metaplay Portal. The telemetry messages highlight potential updates to the SDK or its components.
• New MButtonGroupLayout component: This component makes it easy to create consistent-looking groups of buttons. Notably, it now expands buttons to full width on narrow browsers to keep them legible. We have migrated all our button groups to use this new layout.
• New @metaplay/playwright-configs package: This package provides actions, fixtures, and sensible default configurations for writing tests against the LiveOps Dashboard using Playwright.
• Vitest updated to v2: Vitest has received a major version update. Please refer to the Vitest Migration Guide if you use Vitest for unit testing and encounter errors after the update.

Complete List

• Added: A new MViewContainer component that provides a container for dashboard pages and offers a consistent layout for the page content.
• Added: A new MPageOverviewCard component that provides a high-level overview of a dashboard page and offers quick access to key information and actions.
• Added: A new useNotifications composable that provides a way to show and manage notifications to the user.
• Added: A new "action debouncer" system for correctly debouncing requests to the server without the client code having to worry about multiple, serial overlapping requests arriving out-of-order.
• Added: A new dashboard permission api.players.view_developers for viewing the list of developer players. This allows you to decide who can see the list of developer players in a more granular manner. Previously, this was behind the api.players.view permission, meaning that any user who could view players could also view developer players. If you use custom roles, you will need to add this new permission. Check the migration guide for more details.
• Added: New project configuration files and commands for running game-specific Playwright tests.
• Added: The MTwoColumnLayout component, which provides a two-column layout for structuring dashboard views and components.
• Added: The MThreeColumnLayout component, which offers a three-column layout for structuring dashboard views and components.

• Changed: The following components have been deprecated in favor of the new MetaUiNext components:
  • MetaPageContainer is replaced by MViewContainer.
  • MetaPageHeaderCard is replaced by MPageOverviewCard.
• Changed: All dashboard tests have been rewritten to use the Playwright test runner.
• Changed: The MetaAuthTooltip component has been removed as it was deprecated in favor of using the permission prop in new components.

• Fixed: Fixed a case where subscriptions that used PollingPolicyOnceOnly would never fetch data if the client was offline. The initial fetch would fail, and the poller would never retry. The poller now continues to retry fetching the data until it succeeds once.
• Fixed: Added Dashboard permission checking to the Game Config and Localization Publish and Archive actions. Previously, you could attempt to publish or archive even if you did not have the required permission. Note that final permission checking happens on the server, so the action would not have succeeded if someone had attempted it.
• Fixed: The dashboard error page for new users without any roles now renders properly again.
• Fixed: Improved the Export Player and GDPR Export player actions to make the UI more responsive with large player models and to remove the possibility of accidentally exporting stale data.
• Fixed: MTooltip hover bug where the tooltip would disappear when the mouse hovered over it. It now stays open as expected.

Samples

Complete List

• The EntityKind allowed value ranges have been expanded to use the [100, 300] range that is now the default for the games. The Idler sample also uses the old [30, 50] range to show how multiple ranges can be used.
• The EntityKindCloudGame (which was intended to contain the server-only EntityKinds) has been merged into EntityKindGame. The separation was causing unnecessary confusion for very little gain. You can still keep the separation in your project if you want.

Documentation

• New introduction section: The entire introduction area has been revamped! We have a brand new Getting Started section to help developers hit the ground running even faster with simple examples to ease you into Metaplay's workflow.
• New automated testing guide: The entire automated testing section has been rewritten to provide an overview of the different types of tests you can write for your game and how to get started with writing your own tests. See Introduction to Automated Testing to get started.
  • New article: .NET Unit Testing
  • New article: BotClient Testing
  • New article: LiveOps Dashboard Testing
  • New article: Advanced Playwright Dashboard Testing
  • New article: Advanced System Testing
  • New article: Integration Testing
• New SDK update guide: A new Updating the Metaplay SDK guide was added to help update the Metaplay SDK in your project.

Complete List

• Added: A new Metaplay Compatibility Matrix page that lists the version compatibility of the various Metaplay SDK components.

• Changed: The Introduction to Game Configs page has been replaced in the Getting Started section by the new Setting Up Game Configs page, for a more streamlined introduction. It is, however, still available in the Feature Cookbooks > Game Configs section as Working with Game Configs.
• Changed: The Customizing the Dashboard sections of the documentation have been refreshed. The section now includes information about our latest tooling, component libraries, and up-to-date code snippets for customizing the dashboard.

Known Issues

While we strive to resolve all issues, the following are known issues in this release:

⚠️ Crash on 32-bit Android Devices

Releases 29.0 and 29.1 contain a crash bug on 32-bit ARM devices.

The root cause is that Unity's Burst-optimized Unity.Collections.xxHash3 algorithm implementation relies on unaligned memory accesses which cause crashes on 32-bit ARM devices that only allow aligned memory accesses.

Release 29.2 includes a fix for this issue!

Inconsistent Grafana Heatmap Rendering in Mixed-Release Time Windows

Grafana heatmaps render incorrectly when viewing time windows that span events from both Release 29 and older releases. This issue is caused by a change in the underlying Prometheus library, which has altered the formatting of floating-point numbers in heatmap buckets (e.g., 10 vs. 10.0). As a result, Grafana encounters difficulties when rendering heatmaps containing values in both formats within the same time window, leading to inaccurate visualizations.

To view the data correctly, adjust the time window to display results from only one SDK version at a time, i.e., either Release 29 events only or Release 28 (or older) events.

ESLint 8.x About to Reach End-of-Life

The ESLint plugin used in the LiveOps Dashboard project is scheduled to reach EoL during this release cycle. Unfortunately, the ESLint open-source community has not yet released compatible versions of all the underlying shared configurations.

We are looking to update to ESLint 9.x as soon as the ecosystem is ready.

Unity 2021.3 Deprecation

This release deprecates 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.

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 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 MetaplayRelease29

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.

Update Your EntityKind Registries

With the expanded range of values allowed by EntityKind, you can now use the range [100, 300) in your game. You should also merge the EntityKindCloudGame into EntityKindGame as the separation mainly caused confusion, as we did in our samples.

Migration Steps:

1. The following example shows how to do the same in your game:

     [EntityKindregistry(40, 50)] // Old range for the shared EntityKind registry
     [EntityKindRegistry(30, 50)] // Old range for the unified registry
     [EntityKindRegistry(100, 300)] // New supported range
     public static class EntityKindGame
     {
         // Old EntityKindCloudGame values stay in the [30, 40) range
         <Move old EntityKindCloudGame values here> 
   
         // Old EntityKindGame values stay in the [40, 50) range
         <Old EntityKindGame values>
   
         // New entities can be added in the [100, 300) range
         public static readonly EntityKind NewEntity = EntityKind.FromValue(100); 
     }

   Bug alert!

   Do not change the values of any of your existing EntityKinds! If the EntityKinds are persisted anywhere, their meaning would change when deserializing.

2. Update all code using the now-obsolete EntityKindCloudGame.Xyz to EntityKindGame.Xyz.

     DoSomething(EntityKindCloudGame.MyEntityKind); 
     DoSomething(EntityKindGame.MyEntityKind); 

Move Environment Configs File

The Metaplay environment config file has been moved to ProjectSettings/Metaplay.

Migration Steps:

1. Open the project in Unity to trigger this move.
2. Check that connecting to the different environments works as expected.
3. Commit the changed directory of EnvironmentConfigs.json into your source control.

For Games With Customized LiveOps Dashboard

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

Update the 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. Copy and overwrite .eslintrc.cjs. This updates the ESLint configuration for the project.
2. Copy and overwrite .gitignore. This updates the Git ignore file for the project.
3. Copy and overwrite tsconfig.node.json. This updates the TypeScript configuration for the project.
4. Copy and overwrite package.json. This updates the dependencies and test scripts for the project. Doing so will overwrite some changes to the file that you will now need to revert. This is best done using a file diff tool:
   • Restore the name property inside the file to that of your project. This is typically of the form <projectName>-dashboard.
   • Any game-specific package dependencies that you have added will need to be re-added.
5. Copy the playwright.config.ts file. This adds Playwright support to the project.
6. Copy the tests folder across. This folder includes sample Playwright tests.
7. Remove the cypress.config.ts file if it exists. This file is no longer needed.

Clear and Recreate the Dashboard Dependencies

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

You should ensure that you have Node version 20.16.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.16.0 on Node Version Manager
nvm install 20.16.0
# Use the installed version
nvm use 20.16.0

Migration Steps:

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

Migrate Your Custom Components to Use the Latest MetaUiNext Components

As part of this release, the following components have been removed in favor of the new MetaUiNext components:

• MetaPageContainer is replaced by MViewContainer.
• MetaPageHeaderCard is replaced by MPageOverviewCard.
• MetaAuthTooltip has been removed as it was removed in favor of using the permission prop in new components.

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. Import the new components from the MetaUiNext package:

   import { MPageOverviewCard, MViewContainer } from '@metaplay/meta-ui-next'

2. Replace the removed components with the new components and update the props accordingly.

     meta-page-container( 
     MViewContainer( 
     :is-loading="!ExampleData"
     :meta-api-error="exampleError"
     :error="exampleError"
     :alerts="exampleAlerts"
     permission="example-permission"
     )

     meta-page-header-card( 
     MPageOverviewCard( 
     :id="exampleID"
     :title="exampleTitle"
     :subtitle="exampleSubtitle"
     :is-loading="!ExampleData"
     :alerts="exampleAlerts"
     :error="exampleError"
     data-testid="example-data-testid"
     )

     MetaAuthTooltip(:permission="example-permission") 
       MButton Example Button 
     MButton(:permission="example-permission") Example Button 

For detailed examples of how the new components work, check out our new component documentation.

Migrate From Toasts to the New useNotifications Composable

showSuccessToast and showErrorToast have been removed in favor of the new useNotifications composable to show notification-style messages to dashboard users.

Migration Steps:

1. Update the imports to use the new useNotifications composable:

     import { showSuccessToast, showErrorToast } from '@metaplay/meta-ui'
     import { useNotifications } from '@metaplay/meta-ui-next'

2. Destructure the composable to use the new showSuccessNotification and showErrorNotification methods:

     showSuccessToast('Success message') 
     showErrorToast('Error message') 
     const { showSuccessNotification, showErrorNotification } = useNotifications() 
     showSuccessNotification('Success message') 
     showErrorNotification('Error message') 

Migrate Your E2E Tests from Cypress to Playwright

If you have been using the Cypress test runner for your dashboard tests, you will need to migrate your tests to the Playwright test runner. The new @metaplay/playwright-configs package provides actions, fixtures, and sensible default configurations for writing tests against the LiveOps Dashboard using Playwright.

You can check if you have any of your own Cypress tests by looking inside the gamespecific_tests/e2e folder. If you do, then you'll need to follow the migration steps below.

If you need to continue running your existing Cypress tests instead of migrating them, please contact us, and we can help you set up Cypress in parallel with Playwright.

Migration Steps:

1. Please follow the guide at LiveOps Dashboard Testing as if you were adopting dashboard testing for the first time.
2. Migrate your existing tests one by one and test them as you go. You will be moving your tests from gamespecific_tests/e2e/TESTNAME.cy.ts to tests/e2e/TESTNAME.spec.ts.
3. Delete the gamespecific_tests folder from your dashboard folder when done. This folder is no longer needed.

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_telemetry_messages controls who can view the telemetry messages from the Metaplay portal
• api.players.view_developers controls who can view the developer player list

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_telemetry_messages:  [ game-admin, game-viewer                          ] 
        api.players.view_developers:         [ game-admin, game-viewer, customer-support-senior ] 

For Games With Custom Entities

The following changes affect projects that have implemented game-specific entities.

Replace Usage of ShardingStrategies.CreateService()

The ShardingStrategies.CreateService() has been replaced with CreateStaticService() and CreateDynamicService() to enable services that work with dynamic node scaling.

Migration Steps:

1. In your EntityConfig declarations replace the use of ShardingStrategies.CreateService()`:

    [EntityConfig]
    internal sealed class MyEntityConfig : EphemeralEntityConfig
    {
      public override IShardingStrategy ShardingStrategy => ShardingStrategies.CreateService(); 
   
      // Use this *ONLY* if you use `EntityActor.GetAssociatedServiceEntityId()` to locate the entity:
      public override IShardingStrategy ShardingStrategy => ShardingStrategies.CreateStaticService(); 
   
      // In most cases you should use the dynamic service strategy:
      public override IShardingStrategy ShardingStrategy => ShardingStrategies.CreateDynamicService(); 
    }

Note that the node placement rule given in EntityConfigs NodeSetPlacement applies in both cases.

For Games Using the Leagues System

The following core SDK changes affect projects that have implemented the leagues system:

Upgrade Your League Code

1. ClientSlotCore.PlayerDivision has been renamed to ClientSlotCore.PlayerDivisionLegacy and deprecated. Create a game-specific league client slot in ClientSlotGame.cs and use that instead.

2. Update your constructor calls to LeagueClient to include the new ClientSlot.

3. Increment the schema version and add a migration in PlayerModel.cs to move the old client slot data to the new client slot:

   [MigrationFromVersion(fromVersion: 8)] // Replace 8 with the previous schema version in your project
   void MigrateLeagues()
   {
       // Migrate league client state
       #pragma warning disable CS0618 // Type or member is obsolete
       if (PlayerSubClientStates.TryGetValue(ClientSlotCore.PlayerDivisionLegacy, out PlayerSubClientStateBase idlerState))
       {
           PlayerSubClientStates.Remove(ClientSlotCore.PlayerDivisionLegacy);
           PlayerSubClientStates[ClientSlotGame.IdlerLeague] = idlerState;
       } else {
           PlayerSubClientStates[ClientSlotGame.IdlerLeague] = new PlayerSubClientState();
       }
       #pragma warning restore CS0618 // Type or member is obsolete
   }

4. The PlayerActor needs to be updated to use the new league integration handler methods for communicating with the League system. Refer to step 5 of the Leagues Quickstart Guide and "Joining the League" and "Division Scoring" sections of the Customizing Leagues guides for more information. The gist of it is, that any methods in PlayerActorBase that interact with the League system have now been moved to ILeagueIntegrationHandler and LeagueComponentBase. Any calls to these methods need to be updated to call the new methods on the integration handler of the league.

5. The LeagueManagerOptions class has been moved to the game side. Implement an options class for your leagues that inherits from LeagueManagerOptionsBase, and add the [RuntimeOptions] attribute to it. LeagueManagerActorBase and PlayerDivisionActorBase now need the correct options class as a generic parameter.

       [RuntimeOptions("Leagues", true, "Options for the leagues manager service.")]
       public class LeagueManagerOptions : LeagueManagerOptionsBase { }

6. Change the game-side LeagueManagerConfig to inherit from LeagueManagerConfigBase instead of PersistedEntityConfig. You can leave the config class empty.

   [EntityConfig]
   public class LeagueManagerConfig : LeagueManagerConfigBase { }

7. The game-side DivisionConfig can now be left completely empty by default.

   [EntityConfig]
   // Base class handles everything.
   public class DivisionConfig : DivisionEntityConfigBase { }

8. You'll have to implement a LeagueManagerRegistry that implements the LeagueInfos property. The property should return a list of all the leagues in your game in the form of LeagueInfo objects. For example in Idler:

   public class IdlerLeagueManagerRegistry : LeagueManagerRegistry
   {
       public override IReadOnlyList<LeagueInfo> LeagueInfos { get; } = new LeagueInfo[]
       {
           new LeagueInfo(
               leagueManagerId: EntityId.Create(EntityKindCloudCore.LeagueManager,
                   0), // Value here should be the same as leagueId in the PlayerActor league integration. The ids must start from 0 and increase by 1 for each league.
               clientSlot: ClientSlotGame.IdlerLeague,
               participantKind: EntityKindCore.Player,
               managerActorType: typeof(MyLeagueManagerActor),
               optionsType: typeof(MyLeagueManagerOptions),
               divisionActorType: typeof(MyPlayerDivisionActor))
       };
   }

9. The LeagueRankDetails class has a new DivisionParticipantCount property that needs to be set in the GetRankDetails(int rank, int season) method of your LeagueManagerActor. This also means that you can now vary the number of participants per rank. You can set this value to be the same as DivisionDesiredParticipantCount in the old options class.

10. DivisionDesiredParticpantCount and DivisionMaxParticipantCount have been removed from the LeagueManagerOptions. You should remove them from your options yaml files.

For Games With Custom Network Error Handling

The following changes only affect projects that have custom handling of the networking error states on the client.

Handle TerminalError.ProjectNameMismatchError Error

A new network error condition TerminalError.ProjectNameMismatchError has been added to allow better handling of accidentally connecting to non-matching game servers. You need to handle this in case you have customized the error handling in your game.

Migration Steps:

1. Add logic to handle the TerminalError.ProjectNameMismatchError. You can use the same code as you already use for handling TerminalError.InvalidGameMagic as the two trigger on the same condition.

For Games With Custom Parsers

The following only affects projects that have registered parsers for custom types using the RegisterCustomParseFunc<>() method.

Migrate to the New ConfigParser API

Registering custom parsing for game config types via the ConfigParserProvider.RegisterParsers() method needs to be updated to register the parsers to the ConfigParser instance that is provided as the single argument to the method.

If you need a ConfigParser instance in other contexts, you can use ConfigParser.Instance to resolve the instance.

Migration Steps:

1. Update your RegisterParsers() method to accept ConfigParser as an argument and invoke the parsing methods method via the passed-in parser. For example:

     public override void RegisterParsers() 
     public override void RegisterParsers(ConfigParser parser) 
     {
       ConfigParser.RegisterCustomParseFunc<PlayerReward>(ParsePlayerReward); 
       parser.RegisterCustomParseFunc<PlayerReward>(ParsePlayerReward); 
     }

2. Update the signature of your custom parse methods to take the ConfigParser as an argument and invoke the parsing method via the passed-in parser. For example:

     static PlayerReward ParsePlayerReward(ConfigLexer lexer) 
     static PlayerReward ParsePlayerReward(ConfigParser parser, ConfigLexer lexer) 
     {
       ...
       ProducerTypeId producerTypeId = ConfigParser.Parse<ProducerTypeId>(lexer); 
       ProducerTypeId producerTypeId = parser.Parse<ProducerTypeId>(lexer); 
       ...
     }

Note that the old parse method signature continues to be supported and can be used if you have no need to recursively invoke the parser.

For Games Using Metaplay's Game Config Build Window

If you make use of the Metaplay SDK's Game Config Build Window in the Unity editor, follow the steps below.

Remove Obsolete Unity Editor File

The GameConfigBuildWindowMenuItem.cs file is no longer necessary and can be removed.

Migration Steps:

1. Remove the GameConfigBuildWindowMenuItem.cs file from your project.

For Games With Custom Applications

If you make use of the Metaplay SDK outside of the standard applications (game client, server, or botclient), you need to update the Metaplay core and serializer initialization.

Update Metaplay SDK Initialization

Metaplay now automatically handles the SDK initialization and thus no longer needs to be explicitly initialized. The only exception is initialization code using Unity's [InitializeOnLoad] or [InitializeOnLoadMethod] attribute, if the Metaplay SDK is used within the code.

Migration Steps:

1. Remove any calls to MetaplayCore.Initialize() from within the Unity editor. They are now redundant and should be removed.

2. Replace any other existing MetaplayCore and MetaSerialization initialization with a single call:

     MetaplayCore.Initialize(...); 
     MetaSerialization.Initialize(...); 
     MetaplayCore.Initialize(services =>
       services.ConfigureMetaSerialization("<ApplicationName>")); 

   Substitute <ApplicationName> with an appropriate name for the application, for example "MyGameUtility".

3. Ensure Metaplay SDK is initialized in code using Unity's [InitializeOnLoad] or [InitializeOnLoadMethod] attribute, if you use Metaplay SDK within them. For example:

   [InitializeOnLoadMethod]
   static void MyInitializationMethod()
   {
     // Make sure to initialize Metaplay SDK before using it:
     MetaplayCoreEditor.EnsureInitialized();
   
     ... some code using the Metaplay SDK
   }

For Games Without Shared Code Assembly Separation

In case your project is one that started using Metaplay a long time ago, before the proper separation of the SharedCode/ directory into its own assembly, you'll need to now apply that change.

If your project is affected, you will see the following error in the Unity Editor log and when trying to enter play mode: Metaplay client SDK and user-side game logic code have the same assembly: [...].

Introduce Client-Side Shared Code Assembly Separation

Metaplay now requires the game-specific shared code (e.g. Assets/SharedCode/) and SDK-side shared code (MetaplaySDK/Client/) are in separate Unity assemblies.

Migration Steps:

1. Remove the .asmref in your shared-code folder (e.g. Assets/SharedCode/) which refers to the Metaplay assembly, and replace it with the file SharedCode.asmdef with the JSON contents shown in the error message.

2. Fix any potential inverse dependencies that may exist in case you have modified the Metaplay SDK code.

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.

Removal of SchemaVersion Helpers in PersistedEntityConfig

The SupportedSchemaVersions, CurrentSchemaVersion, and OldestSupportedSchemaVersion helpers in PersistedEntityConfig have been moved to PersistedEntityActor for convenience.

Migration Steps:

1. Replace any usage of the above properties using the new helpers.

    void MethodInMyPersistedActor()
    {
      _log.Debug("Current schema version: {CurrentSchemaVersion}", _entityConfig.CurrentSchemaVersion); 
      _log.Debug("Current schema version: {CurrentSchemaVersion}", CurrentSchemaVersion); 
    }

Outside of entity context, the schema versions can be found with SchemaMigrationRegistry.Instance.GetSchemaMigrator<TPersistedPayload>().SupportedSchemaVersions.

Remove ref from Calls to MetaSerialization.ResolveMetaRefs()

The MetaSerialization.ResolveMetaRefs() method's object obj or T value parameter is no longer taken by reference (ref object obj or ref T value). In your calls to this method, remove the ref keyword from the argument.

Migration Steps:

1. Remove the ref from all calls to the method:

   MetaSerialization.ResolveMetaRefs(..., ref myObject, ...);  
   MetaSerialization.ResolveMetaRefs(..., myObject, ...);  

Renaming Of IEntityAsker To IEntityMessagingApi

The IEntityAsker interface has been renamed to IEntityMessagingApi.

Migration Steps:

1. Update all references to IEntityAsker to IEntityMessagingApi:

   IEntityAsker asker = ...;  
   IEntityMessagingApi messaging = ...;  

Replace Usage of EntityConfig.EntityActorType and PersistedEntityConfig.PersistedPayloadType

The following properties were replaced with methods that now take an EntityId parameter.

• EntityConfig.EntityActorType property was replaced with EntityConfig.GetActorTypeForEntity(EntityId).
• PersistedEntityConfig.PersistedPayloadType property was replaced with PersistedEntityConfig.GetPersistedPayloadType(EntityId).

Migration Steps:

1. Update any code using the old properties with the new properties:

   // Update usage of EntityActorType
   Type type = _entityConfig.EntityActorType;  
   Type type = _entityConfig.GetActorTypeForEntity(_entityId);  
   
   // And usage of PersistedPayloadType
   Type type = _entityConfig.PersistedPayloadType;  
   Type type = _entityConfig.GetPersistedPayloadType(_entityId);  

Migrate Use of MetaplayController.AskEntityAsync()

The AskEntityAsync() method in the MetaplayController API controller base class has been renamed to EntityAskAsync(). The new name is consistent with the equivalent method in EntityActor.

Migration Steps:

1. Change your AskEntityAsync() calls to use the new name EntityAskAsync(). The old method still exists as well but is marked as [Obsolete] so it will produce compiler warnings.

     void MyControllerMethod()
     {
       await AskEntityAsync<...>(...);  
       await EntityAskAsync<...>(...);  
     }

Get Environment Information from RuntimeEnvironmentInfo Instead of RuntimeOptionsRegistry

Server runtime environment information that was previously available in RuntimeOptionsRegistry is now in RuntimeEnvironmentInfo. This concerns members IsRunningInContainer, ApplicationName, and EnvironmentFamily.

Migration Steps:

1. Update accesses to RuntimeOptionsRegistry.<Member> to RuntimeEnvironmentInfo.Instance.<Member>. For example:

       if (RuntimeOptionsRegistry.EnvironmentFamily == EnvironmentFamily.Development)  
       if (RuntimeEnvironmentInfo.Instance.EnvironmentFamily == EnvironmentFamily.Development)  

Change Model Ticks to 64-bit Integers

CurrentTick in PlayerModel and other entity models has been changed from int to long to allow longer simulations to be done during the lifetime of the PlayerModel. If you use the tick counters in your game code, you may need to update your code to use long.

These are the parts of the SDK's API that have changed:

• CurrentTick in all entity models: player, guild, league division, and custom multiplayer entity models.
• DebugForceSetModelTime(MetaTime timeAtFirstTick, long currentTick) in PlayerModelBase.
• Virtual method OnPostTick(long tick) in PersistedMultiplayerEntityActorBase.

Migration Steps:

1. Update any code using ints to operate on CurrentTick to use long instead. For example:

     int ticksToTimerFinish = timer.FinishesAt - CurrentTick;  
     long ticksToTimerFinish = timer.FinishesAt - CurrentTick;  

2. Update any persisted members [MetaMember(...)] storing tick values from int to long, if you have any. Any persisted data can be safely read into the new type long.

     [MetaMember(5)] public int MyTick { get; set; }  
     [MetaMember(5)] public long MyTick { get; set; }  

3. Update any invocations of DebugForceSetModelTime() to pass in a long typed tick value, if you have such calls.

4. Update OnPostTick() signature in classes inheriting PersistedMultiplayerEntityActorBase:

     protected override void OnPostTick(int tick) 
     protected override void OnPostTick(long tick) 
     {
     }

Release 29.1

Released on: August 28th, 2024

Changes

• SDK: Fixed issue with League migration failing when running on MySQL.

For Games Using Leagues

This release only affects games using the Leagues feature. If you're not using the feature, you can ignore this update.

Migration Guide

No additional migration steps are required for this release.

Release 29.2

Released on September 3rd, 2024

Changes

• SDK: Fixed a crash on 32-bit Android devices not supporting unaligned memory accesses in computing model checksums.
• SDK: Fixed an issue where Unity's implementation of xxHash3 produces incorrect outputs for certain buffer sizes by using our vendored implementation for those sizes. This can cause false positive checksum mismatches to be triggered.

For All Games

While the crash issue only affects Android and other ARMv7 games, the incorrect checksum mismatches affects all games.

Migration Guide

No additional migration steps are required for this release.

Release 29.3

Released on September 9th, 2024

Changes

• Fixed: Building an AMD64 docker image to be run in the cloud can now be made on ARM-based devices again.
• Fixed: Updated internal LiveOps Dashboard components to be compatible with Vue 3.5.

For Games Making Docker Builds on ARM Devices

If you are using ARM-based devices to make docker builds of the game server, this release fixes the issue in Release 29 where the builds would fail.

For Games With Custom LiveOps Dashboard

Vue 3.5 (and related language tools) update caused LiveOps Dashboard builds to fail with type errors. This release fixes the issue by updating our components to be compatible with the updated tooling.

Migration Guide

No additional migration steps are required for this release.

Release 29.4

Released on September 12th, 2024

Changes

• Fixed: Updated internal LiveOps Dashboard components to be compatible with Storybook 8.3.

For Games With Custom LiveOps Dashboard

Storybook 8.3 update caused LiveOps Dashboard builds to fail with type errors. This release fixes the issue by updating our components to be compatible with the updated tooling.

Migration Guide

For Games With Customized LiveOps Dashboard

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

Update the Dashboard Project Files

Release 29.3 caused LiveOps Dashboard builds to fail with type errors. This release fixes the issue by updating our components to be compatible with the updated tooling. This causes changes to a configuration file, 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. Copy and overwrite package.json. This updates the dependencies and test scripts for the project. Doing so will overwrite some changes to the file that you will now need to revert. This is best done using a file diff tool:
   • Restore the name property inside the file to that of your project. This is typically of the form <projectName>-dashboard.
   • Any game-specific package dependencies that you have added will need to be re-added.