Metaplay Portal

Introducing the new Metaplay Portal!

Metaplay Portal provides the following key benefits:

• Organization user management - you can invite users into your organization and configure their access to the projects and environments.
• Project and environment management - easily discover where your game's LiveOps Dashboards and Grafanas for each environment are located.
• Machine users and CI support - you can create machine users and use the to configure your CI jobs to build and deploy the game server.
• Evaluate Metaplay for new projects - sign up to the portal and download the SDK to evaluate it for new projects.

If you want to migrate existing projects to be managed from the portal or want to start a new project, please talk to us!

You can sign up to the portal at https://portal.metaplay.dev.

Highlights

• New feature: Server Errors on Dashboard adds a new page to see recent server errors directly from the LiveOps Dashboard for easy visibility into current internal server issues. Go to the overview page in the Dashboard to see the recent error count and to access the errors page.

  

• Async Matchmaker Improvements: The async matchmaker has been improved to support more advanced matchmaking needs, such as supporting storing multiple matchmaker states per player, returning fake results when no suitable match is found, and more. See Deep Dive: Async Matchmaker for more information.

• Major improvement: GameConfigKeyValue Parsing from spreadsheets now supports nested members and multi-cell collections, bringing it to feature parity with GameConfigLibrary sheet syntax.

  

Version Compatibility

SDK

• This release requires a synchronized upgrade of the client and the server due to backward-incompatible changes in the networking protocol.
  • Action required: Bump your game's MetaplayCoreOptions.supportedLogicVersions to force a synchronized update of your game client and server.
• This is the final Metaplay SDK release that supports .NET 7. Release 28 will drop support for .NET 7 and the backend project will only compile against .NET 8. Note that official support by Microsoft will also end on May 14th 2024 (https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core).
  • Action required: Update your server projects to .NET 8 at your earliest convenience!

INFO

Note: If you have a service contract signed with Metaplay, your SDK integration has already been updated to reflect any backwards incompatible API changes in the Metaplay SDK in the SDK upgrade pull request of your project. Otherwise, please see the migration guide for a full list of changes, along with the HelloWorld and Idler samples for references on how to apply the changes.

Infrastructure

We recommend upgrading to the latest versions of the infrastructure and game server Helm chart:

• For infrastructure, terraform module infra-modules v0.2.12.
  • Action recommended: Upgrade your self-hosted infrastructure to use the latest version.
• For deployments, Helm chart metaplay-gameserver v0.5.2.
  • Action recommended: Upgrade your deployments (in Helm values or CI job parameters) to use the latest version.

The minimum required versions are infra-modules v0.2.2 and metaplay-gameserver v0.4.4.

Changes

Live-Ops Dashboard

• SDK folder layout: The MetaplaySDK NodePackages folder has been renamed to Frontend as the old name was often confused with node_modules.
• Mark as tester: The UX flow for updating a player's tester status in experiments. You can now modify the player's tester status either through the join experiment form or by using the new 'Mark as Tester' button on the PlayerExperiment card.
• Experiment audience: Experiment Detail View's Overview Card now has a dedicated Audience section to more clearly communicate how targeting, rollout, max capacity and enrolment triggers affect the total addressable audience estimate.
• Bugfix: Fixed a bug that allowed the active config to be archived.
• Bugfix: Fixed a bug that prevented an experiment's Capacity Limit from being set back to "Unlimited" once it had been set to a number.

Under the hood

• Added: The @metaplay/subscriptions module is now completely standalone and can be used outside of the Live-Ops Dashboard project.
• Added: The @metaplay/subscriptions module now supports passing an HTTP headers object to the fetcher policy when creating new subscription options. Good for passing authentication tokens in requests to external resources, for example.
• Added: The @metaplay/subscriptions module now automatically delays data fetching when the user is not focused on the page. This reduces unnecessary web traffic and improves browser performance for heavy pages.
• Added: MCard has new data-testid props for easier automated testing: card-loading-indicator, card-title, card-badge, card-subtitle.
• Added: MOverviewCard has new data-testid props for easier automated testing: overviewcard-loading-indicator, overviewcard-title, overviewcard-subtitle.
• Added: The MetaListCard component now supports generics for better type safety and editor hints when working with list item templates.
• Added: new MButton, MIconButton, and MTextButton components. These are styled button elements suitable for creating buttons and links in the Live-Ops Dashboard.
• Added: a new MActionModal, designed for actions requiring user confirmation.
• Added: a new MActionModalButton, a composite component that connects the functionality of MButton and MActionModal components.
• Changed: Updated Node to 20.x now that it has reached LTS.
• Changed: PlayerListCard has been improved to show more useful information about players.
• Changed: The @metaplay/subscriptions module now has an initializeSubscriptions() function that needs to be called before using any of the subscriptions. This is automatically done by the core SDK code.
• Changed: All occurrences of data-cy have been renamed to data-testid as the old naming schema was Cypress specific and we are now using the industry standard testid.
• Changed: Replaced the meta-button, meta-action-modal-button, b-button and b-link components with the new MButton, MIconButton, MTextButton and MActionModalButton components.
• Fixed: The @metaplay/subscriptions module now correctly handles multiple chained dynamic subscriptions.

SDK

• Server Entity initialization: The entity initialization has been simplified and changed to happen in parallel. It's now faster and allows cyclical dependencies between EntityKinds during the initialization. The initialization happens one EntityShardGroup at a time and within each group, all entities and entity shards belonging to that group are initialized in parallel.
• Firebase Notifications: Firebase Cloud Messaging notification API usage has been updated, Firebase will discontinue the old API on June 20th 2024. The internals of the new API work differently, and send each notification one by one rather than batched. In our testing, we have not seen a big performance difference, however we recommend testing this in your environments as well. The old API can still be enabled through the PushNotification.UseLegacyApi runtime option, see Working with Runtime Options for more info about runtime options.
• GameConfigKeyValue sheet syntax: now supports structured data with nested members and collections, with similar syntax as in GameConfigLibrary sheets.
• Docker build time validations: A number of common server configuration issues that previously were only caught when the server is booted are now checked already at the docker image build time, by executing the game server executable with newly introduced --MetaplayValidateXXX command line flags. In this release the following validations were added:
  • RuntimeOptions: The various .yaml runtime options files embedded in the server image are now validated against the corresponding options classes in the code.
  • DatabaseModelChanges: Adding EFCore migrations after doing changes to the DB model classes is now enforced.
  • GameConfig: The built-in game config archive is validated against the config code by attempting to import the archive during the build.
• Alpha feature: LiveOps Events: a new SDK feature for implementing in-game events that can be scheduled and targeted directly from the LiveOps Dashboard. In contrast with the existing "activables" feature, the life cycle of LiveOps Events is server-driven instead of relying entirely on shared logic and game configs. In release 27, the LiveOps Event feature is still in an early alpha stage and not yet recommended for production usage. It is likely to undergo significant breaking changes before reaching maturity in upcoming releases.

Under the hood

• Fixed: A bug that prevented session resume from working correctly when the "support multiple client versions" feature was enabled.
• Added: New projects started Release 27 or newer will have the cloud environment Helm values configuration files added in the userland Backend/Deployments/ directory when integrating the Metaplay SDK.
• Added: MetaActionResult now has a virtual boolean IsSuccess property which can be overridden in custom action result types. The SDK uses this to recognize successful action execution, instead of comparing directly with MetaActionResult.Success as before.
• Fixed: The Cypress installation caching in the Dockerfile no longer leaks wrong Cypress versions between docker build invocations.
• Fixed: Optimize a few string allocations in Unity Editor in the timeline event tracking when the timeline history window is not open.
• Fixed: Release package now has the .version file in MetaplaySDK/.version and not in the package root.
• Fixed: FileUtil.WriteAllBytesAtomicAsync() could sometimes execute really slowly on Windows due to the system File.Replace() taking a long time in certain scenarios. It now uses File.Move() which does not suffer from the same issues.
• Fixed: Application._logger now respects the logging configuration specified in the server's Logging runtime options (such as the Json log format), as soon as the runtime options have been loaded. Until now, it erroneously always used the default logging configuration. In practice this affected a few specific log messages logged from Application and its subclasses like ServerMainBase.
• Fixed: Polling rate of UnityEngine.SystemInfo.batteryLevel has been significantly reduced. Querying the battery level can be slow on Android devices.
• Removed: ModelJournal<T>.Follower.ConflictResolutionMode has been removed and all journals assume ContinueEvenIfConflicts.
• Removed: Removed support for MySQL 5.7. The support has been deprecated since Release 19.
• Added: IEntityClientContext.OnEntityDetached hook has been added to allow custom handling for entities becoming inactive for the client, such as in the case a Player leaves a Guild or leaves a certain Division entity.
• Added: Add MultiplayerEntityClientContext.LatencySample.NetworkLatency for observing network latency in MultiplayerEntityClientContext when latency measurement is enabled.
• Added: LatencySimulationMessageTransport to allow simulation of latency. This can be used through MetaplaySDKBehaviour or by injecting it using MetplaySDK.Connection.CreateTransportHooks before MetaplayClient.Connect() is invoked.
• Added: You can now specify the role given to users in non-authenticated environments, ie: environments where AuthenticationType is set to None. You can also disable the ability for users to assume other roles in these environments.
• Added: The new ClusteringMode.Disabled option skips the initialization of the Akka.NET clustering. Useful for apps like BotClient that don't use clustering.
• Fixed: Added player model migrations to places where players are loaded directly from the database in PlayerSegmentSizeEstimatorActor, NotificationCampaignJob and AsyncMatchmakerActorBase. This should result in less rejected players due to errors during segment size estimates, notification campaigns and async matchmaker player scans.
• Removed: Remove metaplay_cluster_services_running_current metric as it doesn't make much sense anymore.
• Added: PlayerLocation now contains the continent.
• Fixed: The database reset logic is now more robust and drops all the tables in the database, not just the ones in the known EFCore schema. It's now able to handle scenarios where a partially run migration could leave some tables in the database undeleted due to partially executed EFCore migrations.
• Fixed: The integration test runs now exit on any logged errors from the server to help catch issues during the tests.
• Added: In Unity Editor game config building and publishing, support the OAuth2 setup used by Metaplay managed environments, which differs from the setup used by most existing environments. This involves a few new properties configuring the behavior of the OAuth2 client. For games running in Metaplay managed environments, the properties can be copied from the Metaplay portal as described in Environment Configs.
• Added: Added early check on server to prevent accidentally running the server in 32-bit environment.
• Added: Added new cause-specific EntityActor.OnSubscriberTerminated and EntityActor.OnSubscriberUnsubscribed hooks that are called in addition to the general EntityActor.OnSubscriberLost.
• Added: Dockerfile.server now supports targeting a different platform/architecture than that of the build host. This is useful for the ability to build server images to be run in the cloud on ARM development setups. The target platform of the docker build can be specified by the --platform flag.
• Fixed: GoogleSheetFetcher now always ensures it downloads the full sheet.
• Added: New AdminApi permission private_blob_file_serve.read that controls access to files served through the PrivateBlobFileServe. By default the permissions is granted to all default roles.
• Added: The gameserver now reports if there are missing EFCore validations by running the executable with command line flag --MetaplayValidateDatabaseModelChanges. This is used by the docker build to catch missing migrations.
• Fixed: Fixed a bug where Unity editor logger early initialization from MetaplaySDK class constructor might cause an exception from accessing Unity APIs from the wrong context. The fix means that editor log messages prior to MetaplaySDK initialization will not be color coded.
• Added: Runtime options .yaml files (for server and bot client) can now be validated against the corresponding options classes by launching the application with flag --MetaplayValidateRuntimeOptions. This is used by the docker build to catch options syntax errors during the image build.
• Added: Server command line flag --MetaplayValidateGameConfig for quick validation that a game config archive file deserializes properly. This is used by the docker build to catch outdated config archives during the image build.
• Fixed: Fixed some MetaSerializable type sanity checks were skipped if the C# project was not in DEBUG mode.
• Fixed: RandomPCG.GetWeightedIndex() now allows zero and negative weights without throwing, such elements are ignored by the method and can never be returned.
• Added: MetaGeneratedUI now allows you to exclude specific types from abstract fields by using the MetaFormExcludeAbstractType attribute.
• Added: Added the localizations build parameters to the LocalizationsBuild.BuildAsync(CancellationToken ct) method, the new signature is LocalizationsBuild.BuildAsync(LocalizationsBuildParameters buildParams, CancellationToken ct).
• Changed: DnsCache.GetHostAddressesAsync will now always return the loopback address when localhost, 127.0.0.1, ::1, or [::1] is resolved, regardless of what other local addresses correspond.
• Added: Added PersistedMultiplayerEntityBase.ExecuteActionAfterPendingActions for conveniently executing follow-up actions from ServerListeners.
• Fixed: Properly support multiple Config item ID aliases in the serialized config representation. The serialization code has a bug that would cause config building to fail if multiple aliases for a single item were present.
• Fixed: Fixed incident reports being uploaded to the wrong environment.
• Fixed: Added better handling to our Unity editor tools of MetaplayCore failing to initialize.
• Changed: GameConfigKeyValue sheets now require a header row specifying Member and Value columns.
• Changed: GameConfigKeyValue sheets now ignore rows where the value cell is empty, leaving the C# member to its initial value. Previously it used to parse the member from the empty string.
• Added: Player login history now also contains client operating system version and the approximate length of the session.

Documentation

• New MetaUiNext components: Documentation for the new MetaUiNext components has been added: MButton, MIconButton, MTextButton, MActionModal, and MActionModalButton. You can find more information about these components and learn how to use them in your project by running pnpm storybook in the MetaplaySDK/NodePackages/MetaUiNext folder.
• New Article: A page describing how to support multiple client versions has been added. You can check it out at Legacy Client Support,
• New article: Working with the Database contains relevant information for using the database within your game, as well as background information how Metaplay uses the database.
• New arcticle: Configuring Cluster Topology explains how to configure the clustering topology for distributed cloud deployments.
• New article: Setup CI to Deploy a Game Server to the Metaplay-Managed Cloud explains how to set up your CI pipeline to build your game server and deploy it into the Metaplay managed cloud.
• New article: UDP Passthrough explains how to host a custom UDP server from within Metaplay.
• Added: New Creating Support Tickets page detailing how to create support tickets and what response time you can expect depending on your contracted support package.
• Added: An Accounts and Authentication page has been added describing the authentication methods the game client uses to connect to the server.
• Update: The Wordle sample and tutorials part 2 (Tutorial: Game Logic) and 3 (Tutorial: Cheat-Proof Gameplay) have been updated with some bug fixes and QOL improvements.

Migration Guide

INFO

Note: If you have a service contract signed with Metaplay, your SDK integration has already been updated!

Database Schema Migrations

To ensure your project has up-to-date migrations for the database schema, generate the migration code with the following:

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

Then, add the generated files into your project's source control. Note that the migration files may come up empty, depending on the features used by your game. If they are empty, you can safely discard the generated files instead. 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.

Configure Managed Environments

If you are using Metaplay managed environments, you'll need to add a set of configuration files for the cloud environments.

Please follow the guide in Release 27 Migration Guide for Managed Environments to add the Helm values files for each environment and the runtime options files for the staging and production environments.

Game Config Changes

The GameConfigKeyValue sheet syntax improvements involve certain changes to sheet content and potentially C# code.

Please follow the Release 27 Game Config Migration Guide.

Custom MetaActionResult Types

MetaActionResult has added a virtual bool IsSuccess() method that returns true when the result should be considered successful. By default, only the predefined MetaActionResult.Success is considered successful.

If you have any classes inheriting from MetaActionResult, you should override the IsSuccess() in them, if they can represent a successful result:

public class MySuccessActionResult : MetaActionResult
{
  // This action should always be considered a successful one
  public override bool IsSuccess() => true;
}

Dashboard Permission to Access Server Error Logs

If you are specifying custom dashboard permission mappings in your runtime options .yaml files, add a mapping for the newly introduced permission api.system.view_error_logs to control which roles can view the server error logs.

See Dashboard User Authentication for further information. When using the SDK-provided default roles, the permissions is automatically granted for GameAdmin and GameViewer roles and no further action is required.

Clustering Initialization Simplification

The clustering initialization has been simplified:

• Remove the InitClusterServices() from your project, usually in ServerMain.cs. The entities to initialize are now automatically detected.

• If you have used any ClusterServiceLocal at the end of the InitClusterServices() list, these can be replaced with the following virtual methods:

  protected virtual override Task StartApplicationAsync() { ... }
  protected virtual override Task StopApplicationAsync() { ... }

Custom Entities Configuration

Related to the above clustering simplifications, there were some modifications to how the server-side custom entities are configured.

If you use custom entities in your game, please follow the Release 27 Migration Guide for Custom Entities to update your custom entities to the new APIs.

NodePackages Directory Renamed

References to the NodePackages folder in the MetaplaySDK need to be updated to the new name of the folder Frontend:

• In pnpm-workspace.yaml, replace

  - MetaplaySDK/NodePackages/*

  with:

  - MetaplaySDK/Frontend/*

• In vite.config.ts, update path in eslintPlugin exclude filters:

    exclude: [
      '**/node_modules/**',
      '**/NodePackages/**', // Added our own monorepo packages to ESLint ignore list so they don't get linted twice.
    ]

  with:

    exclude: [
      '**/node_modules/**',
      '**/Frontend/**', // Added our own monorepo packages to ESLint ignore list so they don't get linted twice.
    ]

• Check for any other references to the old NodePackages directory and rename them to Frontend as well. For example, the Visual Studio Code .code-workspace file may contain such references.

Dashboard Dependencies Updated

In Dashboard/package.json, apply the following diff:

@@ -1,18 +1,18 @@
 {
   "name": "game-dashboard",
   "private": true,
   "version": "1.0.0",
   "license": "Metaplay SDK Software License",
   "type": "module",
   "engines": {
-    "node": "18.x"
+    "node": "20.x"
   },
   "scripts": {
     "dev": "vite",
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
     "lint": "eslint . --fix",
     "backend": "dotnet run --project ../Server",
     "bots": "dotnet run --project ../BotClient -MaxBots=10",
     "test-unit": "vitest run",
     "test-e2e": "cypress run"
@@ -21,36 +21,37 @@
     "@metaplay/core": "workspace:^",
     "@metaplay/eslint-config": "workspace:^",
     "@metaplay/game-server-api": "workspace:^",
     "@metaplay/meta-ui": "workspace:^",
     "@metaplay/meta-ui-next": "workspace:^",
     "@metaplay/subscriptions": "workspace:^",
     "@metaplay/tailwind-plugin": "workspace:^",
     "@metaplay/typescript-config": "workspace:^",
     "@shoelace-style/shoelace": "^2.11.2",
     "@vitejs/plugin-vue": "^4.5.2",
-    "@vue/compat": "^3.3.11",
-    "@vue/language-plugin-pug": "1.8.25",
-    "@vue/runtime-dom": "^3.3.11",
+    "@vue/compat": "^3.4.19",
+    "@vue/language-plugin-pug": "1.8.27",
+    "@vue/runtime-dom": "^3.4.19",
     "autoprefixer": "^10.4.16",
     "cypress": "^12.17.4",
-    "eslint": "^8.47.0",
+    "cypress-recurse": "^1.35.2",
+    "eslint": "^8.57.0",
     "install": "^0.13.0",
     "npm": "^9.6.7",
     "pinia": "^2.1.7",
     "postcss": "^8.4.31",
     "pug": "^3.0.2",
-    "tailwindcss": "^3.3.6",
+    "tailwindcss": "^3.4.0",
     "typescript": "5.1.6",
-    "vite": "^5.0.9",
+    "vite": "^5.0.12",
     "vite-plugin-eslint": "^1.8.1",
     "vite-plugin-static-copy": "^0.17.0",
     "vitest": "^1.0.4",
-    "vue": "^3.3.11",
+    "vue": "^3.4.19",
     "vue-router": "^4.2.5",
-    "vue-tsc": "1.8.25"
+    "vue-tsc": "1.8.27"
   },
   "dependencies": {
     "@tailwindcss/container-queries": "^0.1.1",
     "@tailwindcss/forms": "^0.5.6"
   }
 }

In Dashboard/vite.config.ts, apply the following diff:

 import { defineConfig } from 'vite'
 import vue, { type Options as VuePluginOptions } from '@vitejs/plugin-vue'
 import eslintPlugin, { type Options as EslintPluginOptions } from 'vite-plugin-eslint'

 // https://vitejs.dev/config/
 export default defineConfig({
+  define: {
+    __VUE_OPTIONS_API__: 'true',
+    __VUE_PROD_DEVTOOLS__: 'false',
+    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false',
+  },
   plugins: [

Replace data-cy With data-testid

The Cypress-specific attribute data-cy has been replaced with the more commonly used data-testid across all components and tests. This is needed to enable migration to Playwright in the future.

Replace any usage of data-cy with data-testid:

• In your dashboard components, replace component declarations like this:

  SomeComponent(data-cy="my-id")

  with this:

  SomeComponent(data-testid="my-id")

• In tests, replace queries like this:

  cy.get('[data-cy=my-element]')

  with this:

  cy.get('[data-testid=my-element]')

Replace button and modal components with MetaUiNext components

We are deprecating the following components in the near future. Replace all occurrences of the components in the list below, with the corresponding MetaUiNext components:

• b-button with MButton, MIconButton, or MTextButton.
• b-link with MButton or MTextButton.
• b-modal with MActionModal.
• meta-button with MButton, MIconButton, or MTextButton.
• meta-action-modal-button with MActionModalButton or a combination of MButton, MIconButton or MTextButton with the MActionModal component.

For a comprehensive guide on how to use these new components, run pnpm storybook in the MetaplaySDK/NodePackages/MetaUiNext folder.