Highlights

• Major improvement: Async Matchmaker has new features, full dashboard integration, and a new Integrating the Async Matchmaker.

• New sample project: Wordle clone. The Metaplay SDK package now contains a new sample project that implements a basic clone of the popular "Wordle" game, serving as a Tutorial: Game Logic.

• New experimental feature: WebGL. The Metaplay SDK now has limited support for WebGL builds. See Metaplay & WebGL for more details.

• Major improvement: Upgrade to MySQL 8.x and Aurora RDS 3, enabling instantaneous table schema updates. Support for MySQL 5.7 is now deprecated.

• Major improvement: LiveOps Dashboard TypeScript migration. Conversion of the LiveOps Dashboard integration API and internal libraries in TypeScript, significantly improving the development experience for custom dashboard components.

Known Issues

• We've recently seen ArgumentNullException to be thrown from inside HttpListener when used by the MetaplaySystemHttpServer a few times from our internal test suites.
  • The issue is likely caused by this .NET runtime issue. We have a fix ready for this, but deemed it too risky to include it in the release at such a last moment. We'll do some more internal testing on the fix and either release it in R20 or earlier, depending on how often this occurs.
  • Action: If you encounter this issue, do let us know and let's work together to figure out the best solution.

Breaking Changes

• All dashboard integration APIs have changed during the TypeScript conversion. We will continue reviewing and polishing them over the next few releases.
  • No action required: All projects have been migrated to the updated APIs.
• Some important dashboard dependencies (such as Pinia and Cypress) got major version updates and caused sweeping refactors to accommodate for the changed APIs.
  • No action required: All projects have been migrated to the updated APIs. Keep an eye out for the latest patterns when dealing with mainStore or Cypress tests!
• Dashboard subscriptions and authentication got significantly refactored during the TypeScript conversion and now offer much more mature APIs.
  • No action required: All projects have been migrated to the updated APIs.
• The Options.yaml files have been cleaned from most of the SDK-required options and should now mainly contain game-specific values.
  • No action required: All projects have been migrated.
• The SDK now declares a set of default AdminApi permissions that are used if the project doesn’t specify its own roles & permissions. The runtime option block Authentication has been renamed to AdminApi to better reflect its purpose.
  • No action required: All projects have been migrated.
• Localization must be configured via the new MetaplayFeatureFlags that are passed to the MetaplayCoreOptions constructor.
  • No action required: All projects have been migrated.
• Newtonsoft.Json has been upgraded to v13 in the client (Unity package com.unity.newtonsoft-json v3.0.2).
  • No action required: All projects have been migrated. If you notice any issues during Unity builds, please reach out to us!
• It is no longer necessary to initialize MetaplayCore or MetaSerialization for operations involving the Metaplay SDK within the Unity editor. When the MetaplaySDK package is present in the project, the MetaplaySerializerBuild.InitForEditor() hook will do the necessary initialization automatically.
  • No action required: Existing explicit initialization calls have been removed in projects.

Notable LiveOps Dashboard Changes

• When a user roles does not have the needed permission to navigate to access a particular feature, the sidebar menu now includes a friendly tooltip to help you figure out which permissions are missing.

• A new MetaOverviewList wrapper component allows you to easily add game-specific data to the overview lists.

• A new "safety lock" feature allows you to require an extra click to confirm potentially dangerous changes. The lock defaults to "engaged" in production environments. You can add this to your own buttons by using the MetaButtoncomponent with the safetyLock property set to true.

• The developer UI and safety lock toggles have moved to the user profile page to keep the sidebard cleaner.

• A new 'quick links' feature makes it easy to access other frequently used applications. Access them by clicking on the name of your environment in the header bar. Have a look at the new Configuring the LiveOps Dashboard to customize the links in your project!

• The game configs diff view is now much more performant when viewing very large diffs.
• A new "swap" button makes it easy to quickly swap the diff order between two game configs.
• Experiments list page can now filter experiments based on their phase. Concluded experiments are hidden by default.
• The game server build number and commit ID have been moved to the "Game Server Status" card of the landing page to make them easier to see at-a-glance.
• When one player’s "Player Details" page links to another, the dashboard now updates correctly to show the new player’s details when the link is clicked.

Notable Under-the-Hood Changes

• New development feature: Overwrite player state from client. You can now embed known player states (as exported from the dashboard) in your development builds and use the new DevOverwritePlayerStateRequest development-only request to reset the current player state.
• We have added more configuration the LiveOps Dashboard project files to check for locally installed Node.js version compatibility. This results in much more helpful error messages when a dependency is missing!
• The game server can now be run in local networks without exposing the dashboard to the whole network by moving the CDN emulator to port 5552, which, by default, accepts connections from remote hosts.
• Sample projects have been upgraded to Unity 2021.3.
• The need for configuring assembly stripping in project-specific Assets/link.xml files has been replaced with reading the sdk-side link.xml file during the game build.
• Experiment variant configuration now supports declaring multiple variants in the /Variant column as a comma-separated list, to reduce the need for duplicating information for variants as separate rows.
• The [MetaDescription()] attribute has been generalized and is now used in more features to show human-readable descriptions in the dashboard.
• We've added a new client-server communication primitive on top of raw MetaMessages, the MetaRequest/MetaResponse pair. The new primitive makes it convenient to implement server queries from the client. Currently the transport only supports targeting the session actor, in the future the mechanism can be extended to support queries to server-side entities as well. The client-side API for issuing requests can be found as IMessageDispatcher.SendRequestAsync().
• Apple GameCenter Social authentication now supports Team-Scoped PlayerIds. Utility plugin MetaplayGameCenterPlugin has been added to help fetching both legacy and team-scoped player verification tokens.

Version Compatibility

Infrastructure and Helm chart compatibilities for this release:

• Minimum version requirements
  • Requires infra-modules version 0.1.6 or later for infrastructure
  • Requires metaplay-gameserver Helm chart version 0.4.0 or later for deployment
• Suggested versions
  • Recommended infra-modules version 0.2.2 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.4.1 or later for deployment

Change Log

Breaking (list anything here that needs related changes in the customer projects)

• SDK: Unity build now uses link.xml from the MetaplaySDK client folder and refers to it by GUID. Make sure that you have the file checked in to version control and that the GUID declared in link.xml.meta has not been changed.
• SDK: Due to the serializer initialization change in Unity editor it is no longer necessary to explicitly initialize MetaplayCore or MetaplaySerializer in editor context. Specifically, the function MetaplaySDK.InitSerialization() is now private and calls to it from project editor code should be removed.
• SDK: Added MetaplayCoreOptions.ProjectName that replaces the old EnvironmentOptions.ApplicationName.
• SDK: Application initialization should now use ServerMainBase.RunServerAsync() or BotClientMain.RunBotsAsync() instead of the old methods (those are now protected to avoid accidental usage). The EFCore detection logic was also moved into ServerMainBase, so it no longer needs to be done in the userland ServerMain.
• SDK: A new environment variable METAPLAY_ENVIRONMENT_FAMILY must now be specified when running the server in a container. Helm chart v0.4.0 sets this.
• SDK: Most of the SDK-specific contents of Options.yamls were migrated into the SDK code.
• SDK: Default permissions are now defined in the SDK code. If a project is happy with the defaults, they should delete their config from the .yamls.
• SDK: In local environments, the server will now by default exit immediately if unknown options are given in the option .yaml files. This is controlled by the option Environment:ExitOnUnknownOptions, and is intended for catching errors during local development. In cloud environments, it is disabled by default, and should be kept that way to allow the server and infra to be briefly out of date with each other during backend updates.
• SDK: Client-side Social Authentication failure handler in IMetaplayClientSocialAuthenticationDelegate receives information if failure due to a temporary issue and the potential error message.
• SDK: Client-side Social Authentication conflict handler is given ConflictResolutionId which it must pass in into MetaplayClient.SocialAuthManager.ResolveConflict.
• SDK: GuildActor.CreateGuildDiscoveryInfo now returns a pair of public and server-only info without using GuildDiscoveryGuildData.
• SDK: Guild Name and Description requirements and validation is moved from GuildModelConstants and GuildActor[Base] into a GuildRequirementsValidator integration which the game may override with a custom implementation.
• SDK: Game-specific permissions should now provide default permissions and use [MetaDescription] for the description.
• SDK: Renamed AdminApiPermissionRegistryAttribute to AdminApiPermissionGroupAttribute.
• SDK: CDN emulator is now served at http://localhost:5552 instead of old http://localhost:5550/api/cdnEmulator. Must change all usage to new url. The dedicated server listens to connections from all networks.
• SDK: Format of Authentication runtime options changed and renamed to AdminApi. This affects the definition of roles, permissions and API authentication options. Changes may need to be made to options yaml files.
• SDK: IMetaplayLocalizationDelegate.AllowAppStartWithoutLocalizations is removed and is now controlled by MetaplayFeatureFlags.EnableLocalizations given during init.
• SDK: When config-parsing StringIds containing dots or hyphens, the parsing stops at whitespace instead of ignoring whitespaces. In the unlikely case a project has whitespace in StringIds in configs, they'll need to be adjusted.
• SDK: Metaplay SDK core options are now provided via implementing interface IMetaplayCoreOptionsProvider, replacing the older mechanism using the MetaplayCoreOptionsProvider attribute.
• SDK: Must pass MetaplayFeatureFlags to MetaplayCoreOptions constructor. Specify EnableLocalizations based on whether the project uses the Metaplay localization feature and EnableGuilds if the Metaplay guilds feature is used.
• SDK: SessionActorBase has _state.GameState renamed into _gameState. Session is established if _phase == ActorPhase.InSession (instead of _state != null).
• SDK: If METAPLAY_ENABLE_FIREBASE_ANALYTICS is defined, all members in all Analytics Events must be scalar types, or explicitly ignored with [FirebaseAnalyticsIgnore]. Previously non-scalar types were automatically ignored.
• SDK: BotClient should no longer call PlayerContext.Update or GuildContext.Update. The updates are handled automatically.
• SDK: MetaSerializableFlags.AllowNoMembers is removed. The types must instead be marked with [MetaAllowNoSerializedMembers]. This allows consistent usage with [MetaSerializableDerived] types.
• SDK: Guild Recommender requires temporary ParseLegacyVersion1PoolPage implementation for one-time data migration. Reference implementation is available in idler sample project.
• SDK: Client Listeners for GuildModel are now set with MetaplayClient.GuildClient.SetGuildClientListeners at SDK init time or IMetaplayLifecycleDelegate.OnSessionStarted callback.
• SDK: Removed the IGameConfigDataResolver parameter from config parse functions and the config build function.
• SDK: IMetaplayClientConnectionDelegate.CreateOfflineTransport() is now CreateOfflineServer(). Offline server instance is moved from MetaplayConnection.Delegate.OfflineServer into MetaplayConnection.OfflineServer.
• SDK: The serializer now more strictly requires that when a class derives from a [MetaSerializable] base class, the subclass needs to specify either [MetaSerializable] (if the class isn't intended to be serialized via the base class) or [MetaSerializableDerived(...)]. Previously, the subclass would inherit the [MetaSerializable] from the base class.
• SDK: Guild functionality in PlayerActorBase has been moved to separate PlayerActorGuildComponent. Integrations need to be updated accordingly by moving PlayerActor guild-related overrides into a game-specific PlayerActorGuildComponent derived class.
• BotClient: BotClient actor should no longer implement IPlayerModelClientListenerCore directly as it is already no-op implemented in the base class.
• Dashboard: ESLint 8 may explode the dashboard if the customer project root doesn't have an .eslintrc.json that, for example, disables linting for customer files.
• Dashboard: Integration API got re-structured -> migrate old integration files and check that customer routes put all extra data inside the route meta object instead of route root.
• Dashboard: Routes now need a new meta: { sidebarOrder: number } prop to be placed in a specific position -> migrate old integration files.
• Dashboard: Custom player details components got refactored to use the new subscriptions API -> migrate existing game-specific components.
• Dashboard: MetaListCard filter and sort options refactore to uiUtils.ts -> migrate existing game-specific components.

Added

• SDK: New MetaRequest/MetaResponse client-server communication primitive for more convient implementation of client session messages that expect a response.
• SDK: Support for GameCenter team-scoped TeamPlayerIds. Additionally client may pass both the team-scoped TeamPlayerId and the legacy id to log in with both authentication methods with one query.
• SDK: Support for overwriting player state from EntityArchive json provided by client (available in development environments and for players tagged as developers).
• SDK: Added MetaplayFeatureFlags that can be used to enable/disable features across the client and the server. Initially, localization feature can be controlled via the EnableLocalizations member and the guilds feature via EnableGuilds. The feature flags must be passed to MetaplayCoreOptions.
• SDK: The game config parsing of MetaTime now supports date-time syntax, such as 2022-05-20 12:34:56.789.
• SDK: New ChecksumGranularity PerActionSingleTickPerFrame limits the number of tick checksums to at most one tick per frame which reduces the performance impact when resuming from pause. This used by default.
• SDK: Added Guild Recommender metrics to allow observing update frequency and pool sizes.
• SDK: Added support for adding game code sub clients in the default Unity integration MetaplayClient. They can be passed in with MetaplayClientOptions.
• SDK: InitializeMetaplayProject() now copies the userland Backend/ directory & Server.sln as well.
• SDK: Serialization of a null config reference with a non-nullable key type (e.g. enum) is now supported when the IGameConfigData<>-implementing class defines a static property called ConfigNullSentinelKey. This reserves a key for representing null references in serialized data.
• SDK: Added MetaplayGameCenterPlugin helper for retrieving the Apple GameCenter authentication tokens.
• SDK: Experimental support for WebGL. Has some significant limitations still: only supports offline mode (networking is not implemented), doesn't support localizations or incident reporting.
• SDK: Added the ability to define additional bucketing requirements for asynchronous matchmakers.
• SDK: New EntityComponent framework for defining modular EntityActor components. Currently used for splitting the guild-related actor behaviour of PlayerActor to PlayerActorGuildComponent.
• SDK: Added PlayerActorBase.OnPlayerIncidentRecorded() for game-specific data gathering of player incidents.
• Dashboard: Added a new function into integration.js to easily register custom Vue plugins without modifying code SDK code.
• Dashboard: Added tooltip that shows the required permissons when a sidebar item is greyed out.
• Dashboard: Added a new 'safety lock' feature that can be toggled from the sidebar and is on by default in production. It prevents accidentally committing actions in the dashboard.
• Dashboard: Added a new "swap" button to game config diffs page to quickly swap the diffing order.
• Dashboard: Added a new modal on the sidebar header that provides quick links to other environments.
• Dashboard: Added filtering options to the experiments list card. Defaults to hiding concluded experiments.
• Idler: Added some unit test examples for testing game-specific PlayerActions in Samples/Idler/CloudCore.Tests/PlayerActionTests.cs.
• Idler: Added an example AsyncMatchmaker integration.
• Samples: Added Wordle clone sample.

Changed

• SDK: Upgraded to .NET 6.0.6 (SDK 6.0.301).
• SDK: Upgraded dependencies, mainly Akka v1.4.37, EFCore v6.0.4, MySqlConnector v2.1.8, prometheus-net v6.0.0, MaxMind GeoIP v5.1.0.
• SDK: Default to MySQL 8.0 database. Reduces number of roundtrips to database for improved performance. MySQL 5.7 is considered deprecated now.
• SDK: Refactor of Admin API authentication code to make it easier to add new auth providers.
• SDK: Added new (faster and smoother) Admin API authentication provider based on JWTs.
• SDK: The [MetaDescription] has been moved into the SDK core, and is intended to be used for all new features requiring dashboard-visible descriptions for classes or members.
• SDK: Client-side consistency checks for ticks are throttled to at most 2 per frame. This limits the performance impact when resuming from pause.
• SDK: Mapping of DbSet<> entries in DbContext classes can now be toggled via MetaplayFeatureEnabledConditionAttribute attributes.
• Dashboard: Upgraded Cypress to version 10.
• Dashboard: Made player details page properly reactive to changes in player ID.
• Dashboard: Upgraded ESLint, related plugins and configuration to new major 8.x.
• Dashboard: Significant restructuring of how routes are registered and how route metadata is passed around. More aligned with the underlying vue-router types.
• Dashboard: Significant restructuring of the integration API to make it easier to maintain and extend. No more need for game config callbacks during init!
• Dashboard: Sidebar routes now have a meta property sidebarOrder to easily inject new routes into specific positions from integration code.
• Dashboard: Developer mode toggle has been moved to the users page and is on by default in non-production environments.
• Dashboard: Overview card lists now uses a customizable MetaOverviewList component to display overview card data.
• Dashboard: Game config diffs details are now lazy loaded and closed by default to ease with browser performance when opening very large diffs.
• Dashboard: MetaListCard sort and filter options refactored to uiUtils.ts and TypeScript. This fixes unnecessary and noisy HMR warnings when in local development mode.
• Dashboard: API subscription system overhauled. Improvements include better reactivity and a standardized client API, both leading to more consistent usage patterns.
• Dashboard: Moved server build and commit ID from the sidebar to the overview page.
• SDK: Remove the need of declaring Metaplay assembly preserve directives in project link.xml
• SDK: Unity Editor now always has Metaplay serializer initialized.
• SDK: Successful duplicate IAPs (such as restorations of non-consumables or subscriptions) are now stored in a bounded-length DuplicateInAppPurchaseHistory list instead of the unbounded InAppPurchaseHistory to avoid bloating the PlayerModel in case of repeated purchase restorations.
• SDK: DeploymentVersion was changed from class to struct.
• SDK: By default, server<->client messages larger than 10kB are now deflate-compressed for transmission. This is controlled by the server option ClientConnection:EnableWireCompression.
• SDK: The effective PlayerModel size limit (until session start fails) has been increased from 1MB to 5MB. The size limit is no longer enforced on the client-side, and can thus now be adjusted with just a server update.
• SDK: Change ModelJournals for PlayerModel and GuildModel to work with the SDK-side interfaces rather than the concrete types. This enabled further cleanups of the SDK API.
• SDK: Player Actor analytics events are now flushed when the Model is persited into the DB. This reduces the desync between the model and the analytics stream if the player actor crashes.
• SDK: When config-parsing StringIds, they're now allowed to contain dots (.) and hyphens (-) after the first character. Previously, only dots were allowed, and only as separators between normal identifiers.
• SDK: Unity com.unity.nuget.newtonsoft-json has been upgraded to v3.0.2 which includes Newtonsoft.Json v13.x.
• SDK: Client/Unity/Editor/GoogleApis libraries were upgraded to core apis v1.57.0 and sheets v4.1.57.0 for compatibility with Newtonsoft.Json v13.x.
• SDK: Client-side Metaplay Connection no longer supports automatic reconnect after connection loss during session.
• SDK: Spreadsheet parsing now supports empty value cells for key-value structure configs, when empty input makes sense for the member type.
• SDK: Controlled exceptions form EntityAsk handlers are only handled if the exception originates from the entity itself. Forwarding/Rethrowing another entity's controlled exceptions are no longer supported.
• SDK: EntityAskError base class used for controlled exceptions from EntityAsk handlers has been renamed to EntityAskRefusal to clearly differentiate it from entity-terminating errors.
• SDK: The variant column syntax in config spreadsheets now supports declaring multiple variants per row as a comma-separated list.
• SDK: Incident reports now prefer truncating the client log (by dropping least recent log entries) to avoid the entire report being dropped due to exceeding the report size limit (4MB).
• SDK: Provide more accurate error info for failed dashboard-initiated GameConfig builds, to fix missing failure string in dashboard gameconfig views.
• Samples: Idler and HelloWorld samples now use Unity 2021.3.2f1.
• Samples: HelloWorld active environment is now specified with an enum (instead of just boolean) to easily support cloud-based environments, too.

Fixed

• SDK: Server tolerates multiple parallel social logins of a same platform.
• SDK: Large incident reports (>1MB) during session start are no longer rejected.
• SDK: Log spam reduces if JWKS server is temporarily unavailable by throttling queries after sequential failures.
• SDK: The admin API can now be used to query player states up to 6MB in size, allowing the dashboard to be used to view players whose state moderately exceeds the session-start size limit of 5MB. Previously, in multi-node environments, the admin API query would fail for player states larger than 1MB.
• SDK: Analytics events and their contents are now deep copied when issued. Previously events could share references which allowed inadvertly mutating event payload after being issued.
• SDK: When an abstract class implements a [MetaSerializable] interface, classes inheriting that base class can now be serialized via the base class as the static type.
• SDK: It is now permitted to put the [MetaSerializable] attribute on multiple interface types in the same inheritance hierarchy, as long as they all specify the same MetaSerializableFlags.
• SDK: Firebase Analytics integration now supports StringId-typed parameters.
• SDK: Server Action deadlines no longer trigger unexpectedly early if client is flushing past ticks when resuming from pause.
• SDK: Null config references are now properly serialized as the null value of the key type. Previously, only string and StringId key types were serialized properly for null references.
• SDK: Certain kinds of cyclic type constructions no longer break the serializer initialization.
• SDK: On client, old gameconfigs and localizations are pruned from download cache automatically.
• SDK: System:ClientPorts default value is no longer appended when explicitly specifying the option.
• Dashboard: Fixed display of missing variants in Game Config page when different experiments shared the same variant names.
• Dashboard: Table content adjusts smoothly in smaller screen sizes.
• Dashboard: Player reset and overwrite operations now force the entity event log to refresh appropriately.