Highlights

• Major improvement: The In-Game Mails & Broadcasts System has been updated to require less game-specific logic and includes new features. The same mail types can now be shared by both individual mails and broadcasts using the new experimental Form and View Generation feature. For details, take a look at Implementing In-Game Mail.
• New feature: Entity Size Inspector allows exploring and inspecting the stored data of a player, guild, or any PersistedEntity in the database. The tool allows inspecting the storage size from individual PlayerModel fields to their subfields and all the way to the serialization format signaling. Try it out by clicking on the “Save file size” in the player or guild page in the dashboard, or by opening a specific entity via Technical → Environment → Inspect Entities.
• New preview feature: Form and View Generation allows viewing and editing game-specific types in the dashboard without having to write custom components for them. It is also possible to override single fields, or whole sections of the generated UI if needed. The forms part of the feature is under development and lacks support for more complex types. See more at Working with Generated Dashboard UI.
• Major improvement: Synchronized Server Actions allow the Server to issue a PlayerAction that modifies model fields without causing a checksum mismatch. The client cannot modify or refuse the execution of such an action, making these are convenient for updating trusted, checksummed data in PlayerModel. See the details and limitations in PlayerModel Server Updates.
• New feature: Client-side Analytics Events allows easy streaming of analytics events from the client-side into 3rd party analytics events storage such as Firebase Analytics. See chapter ’Handling Events in the Client’ in Implementing Analytics Events in Game Logic).

Breaking Changes

• This release is not backward-compatible with earlier releases and requires a synchronized client/server update.
  • Action required: Bump the game's LogicVersion to force a synchronized client/server update.
• Ports for connecting to the LiveOps Dashboard and the game server API for locally run development environments have changed. This was because of a conflict over port numbers in the latest macOS.
  • Action required: A locally deployed LiveOps Dashboard can now be accessed through http://localhost:5551 instead of the old http://localhost:8080 address. If you need to access a locally deployed game server’s API, it is now available on http://localhost:5550/api instead of the old http://localhost:5000/api address.
• LiveOps Dashboard dependencies have been updated.
  • Action required: Run npm install once to update to the latest dependencies before running the dashboard locally.
• Game-specific model listeners (such as IPlayerModelClientListener) no longer inherit SDK-side listeners (such as IPlayerModelClientListenerCore, previously called IPlayerModelClientListenerBase). The game and SDK listeners are now separate members of the model. The game-specific events no longer need to adhere to the interface pattern but can choose to use other callback mechanisms.
  • No action required: You may replace the game-specific listener interface pattern with a pattern more suitable for your needs.
• The RandomPCG default constructor has been made private as it was easy to accidentally use it incorrectly. The RandomPCG is now initialized with either RandomPCG.CreateNew() for randomized (non-deterministic) initialization or RandomPCG.CreateFromSeed(ulong seed) to initialize from a predetermined seed.
  • No action required: All existing code has been migrated to the new API.
• Due to the changes in login flow during R16 and R17, any clients running R15 or older trying to connect during maintenance mode will get a connection error and generate an incident report. This behavior can be modified to show an update prompt instead. R17 upgrade should be done from a previous version with R16.
  • Action required: If your game is still running with Metaplay R15, tell us and we can help with the upgrade!
• Changes in the mails & broadcasts system require migrating old MetaInGameMail classes to the new format. The mail-related action semantics have been updated to better match existing needs, and therefore many game-specific actions can be deprecated and replaced with SDK-provided versions.
  • No action required: All existing code has been migrated to the new API.
• Entity event log retention is now time-based, and its configuration in the backend’s runtime options has been changed accordingly.
  • No action required: Existing configuration has been migrated to use the new configuration fields.

Notable LiveOps Dashboard Changes

• The initial loading experience of the Dashboard has been rewritten to make it faster, smoother, and more reliable.
• Offers now track the total lifetime purchases and allow you to sort offers lists based on it!

• A new tool has been added to view the raw entity models stored in the database. For example, you can now click on the model size number on all players and guilds to drill down into what properties take the most disk space to store!

• You can now look at raw information about players. This information is more detailed than the Player Details page but less human-readable. It is useful for diagnosing problems with players who have broken player states that cannot be viewed properly on the Player Details page.

Notable Under-the-Hood Changes

• Upgraded dependencies to .NET 6.0.1, EFCore 6.0.1, and Akka.NET 1.4.32.
• Idler Sample Project now uses the new streamlined integration APIs to act as a better reference for how to integrate Metaplay into a game.
• The built-in MetaplayClient provides better connection error information, with a cleaner division between player-facing error information and technical information intended for analytics and debugging.
• The player and guild event log retention is now primarily based on time, instead of event count. The retention time can be configured as documented in section Storage and Configuration of Implementing Analytics Events in Game Logic. The events are now written in the database in compressed form.
• The game servers now support MySQL 8.0 / Aurora RDS 3 databases in preparation for upgrading the databases to the newer version. MySQL 8.0 allows for more instantaneous DDL operations, such as adding or removing columns.
• Testing a push notification by targeting only a list of selected players no longer causes a full database scan and therefore completes in a fraction of the time it used to.
• Server maintenance mode can now be set per client platform (Android/iOS). This can be used in situations where builds for one of the platforms are known to have issues or an updated version is known to not be available through the platform store.
• Added support for In-Game Player Account deletion to enable compliance with Apple policies. More information in Player Account Deletion.
• Added System.Net.Http and System.Text.RegularExpressions as explicit dependencies to allow specifying versions without known vulnerabilities.
• The database connections are now limited to 5 in development environments. This throttles potential rogue database operations which can help identify them early in development environments instead of getting noticed in production.
• Client-side errors encountered during session negotiation now generate SessionStartFailed Player Incident and the report is report uploaded to the server immediately.
• MetaOfferInfo implementations can now declare RequireInAppProduct to false to allow not having an associated IAP. This can be used to build offers that are purchased via other means, for example, soft currencies.
• Upgraded AWS EKS to 1.21.

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.2.2 or later for deployment
• Suggested versions
  • Recommended infra-modules version 0.1.8 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.3.1 or later for deployment

Change Log

Added

• SDK: Added concept of Client Platform communicated by game clients to the server during the login flow.
• SDK: Support routing analytics events on the client to the application via the new IMetaplayClientAnalyticsDelegate. This allows easy streaming of events to 3rd party analytics libraries.
• SDK: Add AnalyticsEventFirebaseConverter helper class to easily convert analytics events for Firebase Analytics in the client. Only simple parameter types are supported for now.
• SDK: Add PlayerModel.ServerOptions.DeletionRequestSafetyDelay to allow inspecting deletion delay before issuing a deletion request.
• SDK: The SDK-side MetaplayClient now provides player-facing English-language error messages in ConnectionLostEvent.
• SDK: The SDK-side MetaplayClient now registers Firebase messaging tokens to the server if the Firebase Messaging package is detected.
• SDK: Added support for hot-loading GameConfigs when running in offline mode.
• SDK: Analytics events for client-side connection errors are routed to the new IMetaplayClientAnalyticsDelegate, and are also available in ConnectionLostEvent.
• SDK: Added incident reporting for exceptions thrown from client's MessageDispatcher listeners.
• SDK: Added GameConfigBuildUtil class that contains some useful utility methods for building GameConfigs (see Idler for usage examples).
• SDK: Add PlayerSynchronizedServerActions which are like Unsynchronized server actions, except they may modify checksummed field but the execution of the action may be delayed. These actions are issued with PlayerActor.EnqueueServerAction.
• SDK: New DeploymentOptions (requires Helm chart v0.3.1 to be populated): AdminUri for the public dashboard url and ApiUri for the public admin API uri (eg, for uploading game configs).
• SDK: Support for using MySQL 8.0 databases. The database instances must be migrated with in infra update.
• SDK: Add DatabaseOptions.MaxConnectionsPerShard for controlling the database connection pool size. The pool is applied to each shard separately, so total number of connections is NumShards*MaxConnectionsPerShard.
• SDK: If session negotiation fails due to client-side error, the error report is delivered to server immediately rather than having to wait for a successful session later on.
• SDK: Added LoginProtocolVersion to MetaplayCoreOptions to support possible future changes in login protocol.
• SDK: Added MetaOfferInfoBase.RequireInAppProduct that can be set to false for implementing soft-currency MetaOffers.
• Server: Added new metric game_session_start_fails_total for observing the number of successfully logged-in connection that fail to start a session.
• Server: Fallback error page for the missing pre-built dashboard when trying to access it (by default at http://localhost:5550).
• Unity: Added debugging utility for spoofing client platform for the Unity editor.
• Unity: Add support for OAuth2 in Admin Api Authorization (e.g. GameConfig publishing).
• Dashboard: Added Entity Inspector for inspecting the raw data of a Persisted Entity. The tool can be used for inspecting how many bytes individual fields take in the database.
• Dashboard: Offers and offer groups now display total revenue, based on configured IAP reference price.
• Dashboard: Added new wrapper component MetaLazyLoader that stops components from loading and rendering when they are outside the viewport, reducing resource usage when the wrapped component is not visible to the user.
• Dashboard: Added support for automatically generating forms and views from C# types.
• Dashboard: Added page for safely viewing raw player details. This can be useful for viewing players with damaged data.

Changed

• SDK: Upgraded dependencies, mainly: .NET 6.0.1, EFCore 6.0.1, Akka.NET 1.4.32.
• SDK: Add explicit references to packages System.Net.Http and System.Text.RegularExpressions to ensure new enough versions that have known vulnerabilities fixed.
• SDK: FacebookLoginService is split into FacebookLoginService which manages only Login API and FacebookAppService which manages only App Access Token.
• SDK: Facebook Limited Login key validation no longer blindly trusts keyset cache durations but attempts renewal every 5 minutes on cache miss. This improves reliablity on scheduled and unscheduled key rotations.
• SDK: Maintenance mode can now be enabled on a client platform basis.
• SDK: AnalyticsEventRegistry has been moved to shared code. The AnalyticsEventSpec is now a top-level class.
• SDK: Player-requested account deletions are now separated from Admin-initiated account deletions.
• SDK: A push notification campaign targeted only for a selected list of players no longer requires a full database scan.
• SDK: Replace RandomPCG constructors with static factory methods RandomPCG.CreateNew() for initializing to non-deterministic random state, and RandomPCG.CreateFromSeed(ulong) to initialize to a specific seed.
• SDK: Removed NumEntriesToKeepInModel from event log configuration in runtime options to simplify the implementation. Always keeping a number of entries in the entity model has turned out to be unnecessary.
• SDK: Reduce event log related bloat in player and guild models. The amount of metadata in the model no longer scales linearly with the number of persisted events.
• SDK: Persisted entity event log segments are now compressed.
• SDK: Changed entity event log retention to be primarily time-based. Maximum and minimum retention counts still exist for safety.
• SDK: To improve SDK vs user separation, new PlayerModels are now initialized with parameterless constructor followed by an initializer method, instead of a parameter-taking constructor.
• SDK: IPlayerModelServerListenerBase has been renamed to IPlayerModelServerListenerCore and is no longer intended to be inherited by the game-specific IPlayerModelServerListener, but rather to exist alongside it in the model. Same applies to client listeners, and for GuildModel's corresponding listeners.
• SDK: MetaplayClient is now a static class, with the Initialize method replacing the old constructor.
• SDK: Clients now support a WireProtocolVersion range. This allow migrating all projects to the new standard WireProtocolVersion 10 in the future.
• SDK: Action eligibility for execution by client and server is now marked with ModelActionExecuteFlags and is no longer dependent on type hierarchy. This enables actions that may be issued by both the server and the client.
• SDK: New player inbox implementation: mail item state is now stored separately from contents in PlayerMailItem classes. Existing mails are migrated to the new inbox in PlayerActor migration. The base PlayerMailItem class maintains generally useful state info about mail items in the form of timestamps.
• SDK: Player inbox mutating actions now use the new PlayerSynchronizedServerAction execution strategy and therefore the inbox data is no longer tagged NoChecksum.
• SDK: The PlayerConsumeMail action no longer deletes a mail item. The previously server-only action PlayerDeleteMail can now be issued from client as well instead.
• SDK: Mail items are now identifier by a globally unique ID of the mail contents in favor of the local inbox running integer.
• SDK: Development environments are by default limited to 5 database connections per shard. The intention is to detect problems with excessive database connections in dev environments before they go into production.
• SDK: Legacy uncompressed GameConfig delivery mechanism has been removed.
• SDK: Reordered login flow to check maintenance and developer bypass before LogicVersion.
• SDK: CloudCoreVersion.cs was moved from userland to SDK MetaplaySDK/Backend/CloudCore/.
• AdminAPI: If server rejects Localization update on /api/localizations, it now returns 409 with an error message instead of a generic 500.
• AdminAPI: If server rejects authenticated request due to a missing permission, it now returns 403 with an error message describing which permission it lacked.
• AdminAPI: When running a local dev server, the API port has been moved from 5000 to 5550. This was due to conflicts on port 5000. You can now find a locally running API server at http://localhost:5550/api.
• Dashboard: When running a local dev server, the Dashboard server port has been moved from 8080 to 5551. This was due to potential conflicts on port 8080. You can now find a locally running Dashboard server at http://localhost:5551.
• Dashboard: Cypress tests now have improved test skipping (by feature or by filename) for easier game specific forking and merging.
• Dashboard: Added new MetaTeleport component to dynamically change page header bar titles based on page content. Initially wired up to always display the current player name in the player details page.
• Dashboard: Subscriptions can now mutate data (eg: to fix issues with the data in one central place) before distributing it to the rest of the Dashboard.
• Dashboard: Segments and experiments that don't have display names or descriptions set now use placeholder text instead of showing nothing.
• Dashboard: Startup and authentication rewritten to improve initial loading experience.
• AdminAPI: Entity event log requests now use a cursor-based scanning API instead of specifying a range of log entry IDs.
• Idler: Migrate sample project to use the new streamlined integration APIs.
• Idler: Cleanups to the GameConfigBuilder workflows.
• Dashboard: Changed mails and broadcasts to use new generated views and forms.

Fixed

• SDK: Fixed bug in session resource proposal code that sometimes caused a non-existing localization (id, version) pair to be reported.
• SDK: Fixed server delivering malformed GameConfig Archives if client did not support compression.
• SDK: Database throttle queues are now replica-specific. A single replica degrading will no longer cause throttling on other replicas.
• SDK: When a dynamic-content IAP purchase does not fully complete during a single session, it is now more robustly completed on a subsequent session, instead of leaving the store purchase in pending state and producing repeated warnings about missing dynamic content.
• SDK: Fixed an issue that prevents developer bypass during maintenance if client had been previously redirected to another environment.
• SDK: The update-cloudcore-versions.sh now gets invoked with an explicit /bin/bash prefix so that it doesn't need the executable bit set (it is easily lost when working on the files in Windows).
• Dashboard: Fixed the link to Grafana on the dashboard overview page.
• Dashboard: Improved medium-narrow browser window layouts to be more readable.
• Dashboard: Game Config detail page loads more quickly.
• Dashboard: Improved performance of entity event log cards when displaying a very large number of events.
• Unity: OfflineServer uses latest language version in source tree.