Highlights

• Major improvements to scalability and clustering robustness. The whole clustering implementation was re-written from the ground up to ensure scalability to millions of daily active users, and beyond. So far, the new code has been tested with 100 000 concurrent bots and we expect it to scale well beyond that. For robustness, chaos testing was used which periodically kills a random subset of all the server shards in the cluster, and waits for a while for the cluster to recover. The chaos testing was done with 10 000 concurrent bots being connected to the cluster and fully recovered every time within two minutes.
• In-game mail improvements. Mails can now have arbitrary, game-specific attachments like items (new MetaReward type). They can be pre-filled based on IAPs for convenience and can also be deleted from the LiveOps Dashboard. Have a look at Implementing In-Game Mail for more information!

• Player Export/Import is a new feature that allows you to copy and paste players - even between different deployments. This will help you out with development and testing - restoring players to previous states to repeatedly and easily test late game features. You can also use it to take players from your live game and import them into your dev environment for safer debugging of player issues. Have a look at Player Export/Importfor more information!

• Robust game sessions. Short connection losses no longer end the session immediately, but instead, Metaplay will attempt to resume the session with a new connection. The session is ended if Metaplay fails to create a new connection before a timeout. MetaplayConnection.Config has new fields for configuring the client-side session timeout.
• Google Play refunds. You can now request in-app-purchase refunds directly from the LiveOps Dashboard instead of copy/pasting transaction ID's manually to the Google Play publisher console! Have a look at Google Play Refundsfor more information!

• A new attribute [MetaBlockedMembers(tagIds..)] was introduced to avoid accidentally recycling old, removed [MetaMember(tagId)] tagIds, which can cause deserialization to fail, or even more subtle bugs to appear. When removing previously serialized members, do add them as blocked to avoid future problems, like this:

  [MetaSerializable]
  [MetaBlockedMembers(7, 8)] // Deprecated members: NumGems, NumGold
  public class BroadcastMessage
  {
   ...
  }

• The initial version of the Metaplay Kubernetes operator was released and currently supports GameServer Kubernetes resources via the metaplay.io/v1 Kubernetes API. These resources can be used to control the deployment of game server pods and are capable of doing coordinated deployments and updates of sharded game server setups for faster deployments in larger-scale setups. metaplay-gameserver Helm chart was updated to optionally use the new GameServer resource type using the experimental.metaplayOperator flag in the chart.

Breaking Changes & Migration

• In-game mails have been refactored to new base classes. All mail types should derive from MetaInGameMail and we also added MetaInGameGenericPlayerMail for convenience so you don't necessarily have to implement your own mail type at all. A lot of the previous game-specific code regarding mail handling is now generic 🎉

  • We went ahead and refactored your existing mail code to derive from these base classes and accept MetaReward attachments. Our implementation is not backwards compatible with old mails. We tried our best to test the mails from as many angles as we could in your project, but please properly review the implementation before deploying to production!

• New MetaReward base class to describe game-specific things that the players can gain, like experience, gold, or items. Any game-specific rewards that derive from MetaReward can be sent as mail attachments. The long term intention is to make MetaRewards the main data-driven way to describe all rewards in the game, like IAPs, to power future LiveOps Dashboard features.

  • To adopt and utilize MetaRewards, you will need to define your game-specific reward types. We implemented a few rewards in your project to get started. Have a look at Implementing MetaRewards for a complete guide to adding new ones!

• Player Export/Import was in preview in Release 6, but we changed and updated the data format for Release 7.

  • If you wish to import Release 6 players into Release 7 then talk to us and we can convert them for you.

• We have updated the metaplay game-server Helm chart (0.0.14) to support multiple game server ports with the .Values.service.ports parameter. This deprecates the .Values.service.port parameter.

  • If you have not explicitly defined.Values.service.port before, then everything will continue as is. Otherwise please update to using the new port configuration structure, as illustrated in the default values in the metaplay-gameserver chart.

• The new clients using robust game sessions won't be compatible with old servers; thus, new servers should be deployed before releasing new clients.

  • Please roll out release 7 servers before releasing release 7 clients.

• Robust game sessions may cause extended times during a game session where the game may seem to continue seamlessly even though there's no connection.

  • You may want to consider adding a connection healthiness indicator in your game. Please see Connection Management for more information.

• MetaplayConnection now has support for tracking application pauses and reacting in certain ways when resuming from a long pause.

  • You may want to call MetaplayConnection.OnApplicationPause from your game. Please see Connection Management for more information. Note: we may have already added this call during the release 7 merge.

• A few new error states have been added to ConnectionStates.

  • Please consider if you'd like to add specific user-facing descriptions for the error states in your game.

• Google Play refunds requires initial setup and need to be configured before using.

  • Please follow the steps in Google Play Refundsto get started!

• A new entity shard type DiagnosticTool has been introduced. For non-singleton server configs, it needs to be added to your Helm chart as the first item in the shards.entityKinds array for every shard type.

  shards:
    ...
    entityKinds:
      - DiagnosticTool
      - GlobalStateManager
      - GlobalStateProxy

  • Any actions the developers should take? @Tuomo Jorri No, the changes are described above

• A new method PlayerModel.FastForwardTime() was added to handle scenarios where PlayerModel.Tick() was not called and player time progression may have been unaccounted for. This only applies to progression that was dependent on Tick() getting called.

  • If you have such logic, please ensure that FastForwardTime() also moves the logic forward. If you have no such logic, there's no need for action.

• Dashboard file and import structure has been refactored for a cleaner user land / core split. Core code now lives in the metaplay_core folder with game specific code in game_specific. All modifications to files under metaplay_core should be tagged with // METAPLAY_CHANGED for easier tracking.

  • *No action needed: we have migrated your existing dashboard code!*🍺

• Human players and bots now have separate EntityId value ranges. The first 4 billion (32 bits) of the id range are reserved for bots and the rest for humans. A new server config variable AllowBotAccounts has been added to only allow bots in non-production environments.

  • No action needed: we have migrated your existing code. Any players that may have been given an id in the low range won't be affected in any way.

• Parts of Game.Server.ClientConnection has been refactored into the new SessionActor. Most game-specific session-level server functionality should now be implemented in SessionActor.

  • No action needed: we have migrated your existing code. New game-specific session-level server functionality should be implemented in SessionActor, if possible.

• Parts of PlayerActor has been refactored into a game-agnostic PlayerActorBase base class, while making PlayerActor a derived class and keeping game-specific code there.

  • No action needed: we have migrated your existing code. New game-specific player actor functionality should continue to be implemented in PlayerActor, if possible.

• The [MetaMessage] attribute now more strictly requires specifying its parameters: the MessageDirection parameter is required for all MetaMessages in order to prevent cheaters from sending server-internal messages from the client. Furthermore, the MessageTargetActor parameter is required when the direction specifies that the message can be sent from the client to the server.

  • No action needed: we have migrated your existing code. New MetaMessage types will need to specify these previously-optional parameters in their attributes as described above.

• Metaplay games can now connect to the server on multiple ports, in order to circumvent potentially blocked ports in restrictive networks.

  • In order to enable the multi-port listen, ensure that the relevant Helm charts have all the ports specified:

    service:
      ...
      ports:
      - name: game
        port: 9339
        targetPort: 9339
        tls: true
      - name: game-443
        port: 443
        targetPort: 443
        tls: true
      - name: game-1863
        port: 1863
        targetPort: 1863
        tls: true
      - name: game-5061
        port: 5061
        targetPort: 5061
        tls: true
      - name: game-3724
        port: 3724
        targetPort: 3724
        tls: true

  • Also, add the following to Assets/Resources/DeploymentConfig.asset for the matching environments. This causes the client to use alternative ports when connecting.

    BackupGateways:
        - Id: alt-port-https
          ServerHost:
          ServerPort: 443
          EnableTls: 1
        - Id: alt-port-1863
          ServerHost:
          ServerPort: 1863
          EnableTls: 1
        - Id: alt-port-3724
          ServerHost:
          ServerPort: 3724
          EnableTls: 1
        - Id: alt-port-5061
          ServerHost:
          ServerPort: 5061
          EnableTls: 1

• New Connection Errors have been added to Metaplay SDK and the game client should add proper error handling for the new error states as described in Connection Management Error List. In particular, the new SessionForceTerminated error is TransientError. However, in case the SessionForceTerminated.Reason is a SessionForceTerminateReason.ReceivedAnotherConnection, the game most likely should not immediately reconnect, but instead, prompt the user. Otherwise, a user logged in on two devices at the same time will immediately get logged out as the competing reconnects kick each other out.

  • Action needed: Consider adopting the new connection errors in your game.

• To support the new Metaplay Kubernetes operator in your own infrastructure, you will need to manually add the Metaplay CRDs to your cluster. You can do this by obtaining the metaplay-services Helm chart, extracting it, and applying the CRD to your cluster:

  wget https://metaplay-charts-stable.s3-eu-west-1.amazonaws.com/metaplay-services-0.0.10.tgz
  
  tar -zxf metaplay-services-0.0.10.tgz
  
  kubectl apply -f metaplay-services/crds/metaplay-operator.yaml

• All runtime database accesses have been ported to use Dapper. Previously, the queries used EFCore, which was detected to use blocking socket IO in the underlying database library. This could lead to thread pool starvation (see, eg, this article). Dapper uses only async IO, which avoids these problems. Initialization-time queries, such as database migrations, still use EFCore.

  • No action needed: all database queries should have been ported to Dapper by us.

• The Entity-to-Entity PubSub communication has been rewritten to be simpler and more robust. This fixes issues where messages could previously leak from already unsubscribed channels. The change also gets rid of Akka.NET remote watches, which caused instability when nodes tried to reconnect after network issues.

  • No action needed: All code has been ported to use the new APIs.

Change Log

Added

• SDK: MiniMD5 helper, which computes the first 32 bits of MD5 without allocating memory (for short string inputs). Can also be computed in MySQL.
• SDK: Support passing in CI build number and git commit id as build args to Dockerfile(s).
• SDK: Resumable game sessions (tolerance for short-duration connection losses).
• SDK: Added MetaBlockedMembersAttribute, which can be used to block retired MetaMember tag ids to be used in the future, to avoid accidental migration problems.
• SDK: Generic attachment mechanism for including items/resources/whatnot in admin messages.
• SDK: New MetaReward base class that can be used to easily attach rewards to thing like in-game mail, events, quests, etc.
• SDK: Added RandomPCG utility methods ShuffleInPlace(T[]), ShuffleInPlace(List<T>), and extension method IEnumerable<T> Shuffle<T>(this IEnumerable<T>, RandomPCG).
• SDK: New Entity DiagnosticTool, which monitors the health of the cluster connections.
• SDK: Server can now listen to multiple client ports, to allow circumventing some networking issues.
• SDK: Client can now fallback to alternative ports if the primary address and port are not reachable.
• SDK: Added Entity Archive feature to allow easy export and import of entities between deployments
• SDK: Added new MetaplayConnection.Errors: NoNetworkConnectivity, FailedToResumeSession, SessionForceTerminated, SessionError, SessionLostInBackground.
• Reference project: Added a new MetaInGameGenericPlayerMail class with sensible default members (title, body, attachments) to make adopting in-game mails easier.
• Reference project: Botclient can now simulate app being put on background for a moment.
• Dashboard: Refactored the in-game mail sending UI to be data driven and to support arbitrary attachments, like resources and items.
• Dashboard: Added the ability to delete player mails.
• Dashboard: Added the ability to request refunds for Google Play purchases.

Changed

• SDK: Rewrite of clustering logic for a more robust and scalable implementation.
• SDK: Separate PlayerId ranges for bots and players to avoid potentially confusing the two.
• SDK: Database data accesses are now implemented using Dapper for improved performance (schema operations still use EFCore).
• SDK: Use ConfigureAwait(false) in many more places to improve scheduling of Tasks.
• SDK: Authentication flow is now simpler and more robust, and bot-specific paths are clearly separate.
• SDK: Player PubSub has been rewritten and is now more robust, has more features and is more performant.
• SDK: Use new MiniMD5 when sharding items in database. Enables efficient up-sharding in the future.
• SDK: Refactored in-game mails to better separate user land and core SDK code. Mails now derive from MetaInGameMail.
• SDK: MetaMessageAttribute now more strictly requires specifying its direction and target actor parameters.
• SDK: Graceful shutdown endpoint is now at :8888/gracefulShutdown (only intended to be used by the Kubernetes operator).
• SDK: Renamed HealthProbeHttpServer to MetaplaySystemHttpServer and related runtime configs are now EnableSystemHttpServer and SystemHttpPort.
• SDK: Support reporting OnApplicationPause to MetaplayConnection, and report a specific error after a long pause.
• SDK: Upgrade Akka.NET to v1.4.10.
• SDK: Upgraded server runtime base image to v3.1.8. Manually include GeoTrust Global CA cert to ensure GameCenter authentication still works.
• SDK: Server now ignores unknown EntityKinds in cluster shard configuration. Useful when deploying new types of entities: can add to Helm values file first, then deploy the server change.
• SDK: ServerRuntimeConfig.ClientPort has been replaced with ServerRuntimeConfig.ClientPorts -- multiple listen ports can now be defined instead of one.
• SDK: Rewrote Export Player and Overwrite Player feature to use new Entity Archive feature.
• SDK: EntityActor.AllowShutdown is removed in favor of EntityActor.ShutdownPolicy which allows for more precise automatic entity shutdown.
• SDK: Refactored PlayerActor into a game-agnostic PlayerActorBase base type and a game-specific PlayerActor derived type.
• SDK: Introduced an IPlayerModel interface for separating the game-specific representation of parts of PlayerModel that are referred to by SDK.
• Dashboard: Refactored in-game mail API and client components to understand attachments. Game specific code was separated to individual, reusable components in anticipation of future use cases.
• Dashboard: Improved workflow of reconnecting new players to their old accounts.
• Dashboard: Added nicer error reporting for Auth0 connection issues in local development mode.
• Dashboard: Improved UI for Export Player and Overwrite Player.
• Dashboard: Added access to new Import Game Entities feature.
• Dashboard: Restructured project files for easier game specific forking and merging.
• Reference project: Auto-reconnect after a long pause.
• Reference project: Better error message when starting the game in Unity with dangling Assets/Metaplay/Metaplay.Generated.dll from previous build.
• AdminApi: Improved and more consistent handling and response for errors.

Fixed

• Dashboard: Fixed header username being hard to read on narrow aspect ratios.
• SDK: Base client-side game update ticks on wall clock time more robustly instead of relying on Unity's deltaTime.
• SDK: Fix CsvReader to be able to parse base class properties with private setters.
• SDK: Fix time progress loss issue by adding PlayerModel.FastForwardTime(), which is called by PlayerActor when actor is live, but client doesn't progress the game clock.