Highlights

• New feature: Runtime options. A major change to the way that we configure the game server. Moving from .json based format to .yaml has made the files easier for us humans to understand. It's also easy to use the system for configuring your game-specific features. We've also added optional hot-loading so that you can change the server's configuration without having to restart it. Finally, to round off this powerful new feature, we included a dedicated page on the LiveOps Dashboard for you to check exactly how your server is configured. Take a look at Working with Runtime Options for more details.

• New feature: Audit logs. All dashboard actions can now leave a trail that makes it easy to check the history of what has been done in a deployment. Turning authorization on will add further details about who performed the action in question. Logs can be viewed per player or searched via the new dedicated audit logs page. For more details, have a look at LiveOps Dashboard Audit Logs

• Experimental feature: Guilds. We have added a basic framework for creating player guilds. The framework allows a player to create, join, leave and interact with a guild. It also contains hooks for the game to implement a guild search & recommendation system and player role and permission management in a way that fits your game. The guild framework is still work-in-progress and there is no complete example implementation or documentation yet!

• Experimental feature: Player segmentation. We have added the groundwork for defining player segments based on conditions on the player state. This feature is still under construction and currently requires some game-specific work, but is already usable. We've included some example code behind #if METAPLAY_R10_SEGMENTATION_AND_OFFERS_EXAMPLE guards. See Implementing Player Segments for more information.

• Experimental feature: Shop offers. We are working on a complete example implementation of IAP shop offers that utilizes player segmentation and a new concept called Activables to serve custom game-specific shop configurations to players. See Getting Started with In-Game Offers for more information.

• Numerous LiveOps Dashboard improvements. For example:

  • Player incidents have their own dedicated page. 3-02_at_16.32.45.pn

  • Player incident types are now clickable, so you can dig into the instances of the given type.

  • Game configs have a more mobile-friendly layout with collapsible sections for easier navigation around very large configs.

    ![](images/r10-configs-mobile-layout.png)
    

  • Game server cluster high level information added to the environments page

    ![](images/r10-server-cluster-info.png)
    

  • Game icon added to the top left corner for a bit of personality ✨

    ![](images/r10-game-icon.png)
    

  • The production environment is now highlighted with red color in order to avoid accidentally doing things in production when the intention was to modify another environment.

  • New data-based workflow and LiveOps Dashboard tools to easily work with roles and permissions. For more information, have a look at Dashboard User Authentication

    ![You can use the "assume roles" feature to quickly test how the dashboard looks for your custom defined roles.](images/r10-assume-roles.png)
    
    You can use the "assume roles" feature to quickly test how the dashboard looks for your custom defined roles.
    

• Added support for Sign in with Apple and Google Sign-In social logins.

• The server can now resolve a player's country based on their IP address. See Implementing Player IP Geolocation.

• Added support for IPv6-enabled dualstack load balancers for game servers. This can be enabled in the metaplay-gameserver Helm chart version 0.2.0 by setting Helm value experimental.gameServerIpv6Enabled to true. This requires that the underlying infrastructure is at infra-modules v0.1.2 or later (and more specifically metaplay-operator v0.0.7 or later). When enabled, the game server's load balancer will be changed from IPv4-only to dualstack mode and the game server deployment will register a [deployment]-ipv6.[domain] DNS AAAA record for the IPv6 load balancer endpoint (for example, when enabled idler-develop.p1.metaplay.io would additionally receive a idler-develop-ipv6.p1.metaplay.io endpoint).

• Updated Loki and Grafana in infra-modules v0.1.2 to enable more powerful querying of structured and unstructured logs. This is enabled by Loki 2.0's more powerful query time label extraction and parsing.

  • For detailed examples of what you can do, please refer to the Loki release notes.

Breaking Changes

• With the introduction of Runtime Options, the naming of all the options has changed. Any scripts or CI jobs passing in environment variables or command-line arguments need to be updated to the new naming. This applies to both Server and BotClient projects.
  • We have updated all the usage that we knew of, but it's possible we missed some. The mappings should be fairly straight-forward, and the new names can be checked from the dashboard on the 'Runtime Options' tab, or in code by searching for all the deriving from RuntimeOptionsBase.
• infra-modules v0.1.2 removes load_config_file references from Kubernetes and Helm providers to fix deprecated settings in providers. We have added minimum requirements of >=2.0 for both Helm and Kubernetes providers in the modules. If you have pinned either of the providers to pre-2.0 versions, you will need to un-pin them or move them to allow >=2.0 versions prior to updating.
• metaplay-gameserver 0.2.0 Helm chart deprecates old JSON runtime configs and requires new YAML-based runtime options. This means that the 0.2.0 chart requires the deployed game server to be at least at Metaplay SDK R10. Additionally, this requires infra-modules v0.1.2 or later to ensure that infrastructure-configurations are provided in YAML format to the game server.
• metaplay-gameserver 0.2.0 Helm chart deprecates experimental.metaplayOperator and experimental.healthzProbeEndpoints parameters. The chart now assumes the presence of a metaplay-operator Kubernetes operator in the cluster and assumes the game server to implement standard /healthz API endpoints for health checking. This affects only very old game server and infrastructure versions.
• metaplay-gameserver 0.2.0 Helm chart deprecates database.backend option and forces it to now always be MySql. This means that the possibility to run Sqlite backend is now deprecated and deployments in e.g. p1.metaplay.io with the new chart will always use the MySQL database backends.

Under-the-Hood Highlights

• The new EntitySynchronize allows performing operations on multiple EntityActors such that no other operation may intervene in the middle of the multi-entity operation. This is useful for building pseudo-transactionality between multiple entities, e.g., It does not guarantee that the operation is fully executed in error scenarios, though.

• Metaplay now performs compatibility version checks with the infrastructure and Helm chart versions, to avoid potential issues from accidentally mixing and matching incompatible versions.

• Role-based authorization for users of the Admin API and LiveOps Dashboard has been overhauled to provide a solution that is easier to configure and more clear to use for developers, CS agents, and CS admins.

• Authorization for the Admin API and LiveOps Dashboard now takes place even when user authentication is disabled (eg: when developing and testing with a local server) making it much easier to spot authorization issues before they get to a deployed server. Developers are able to assume different user roles during testing so that they can see the LiveOps Dashboard exactly as their users would.

• Akka.NET has been upgraded to v1.4.16, which significantly improves CPU usage in low-utilization situations. This should give more realistic CCU/core performance numbers in load tests at lower CPU utilization.

• The serializer now supports nullable primitive types, such as int? and F64?.

• Serialization limits of string and byte array sizes have been increased to 64 MB in order to help with large entity archive exports. At the same time, the server now has stricter size limit checks for payloads sent by the client.

• MetaActionResult is now a class to have a human-readable name and enable including parameters for more complex operations. Common results are instantiated as static readonly members to avoid memory allocation overhead during runtime. The pre-allocated ActionResults can be defined like this in the game's ActionResult class:

  public static readonly MetaActionResult InvalidProducerId = new MetaActionResult(nameof(InvalidProducerId));

• The underlying Entity system (mainly EntityShard class) has been made more robust by protecting it against malformed requests and data in multiple places.

• GameConfigs (including localization data) can now be persisted in binary, making the parsing much faster and allocate much less memory. It is also more robust as the potentially culture-dependent parsing can be done as a preprocess, and the runtime only loads the binary.

• New GameConfigBuilder makes Google Sheet parsing more robust and easily customizable with game-specific parsing passes. The new builder is also much less dependent on Unity, making it easier to invoke from outside of Unity (eg, from the server or CLI-based tools).

• The device Id is now remembered for each registered Firebase Messaging token. When switching player accounts by social authentication, the messaging token for the detached device is now correctly removed. This fixes notification campaigns sending duplicate notifications to devices that have switched accounts.

• Notification campaigns now clean up unregistered Firebase Messaging tokens. Over time, this helps notification campaigns avoid spending unnecessary time attempting to send notifications to invalid tokens.

• GameConfigLibrary now holds the items in the same order as in the source items it was created from. Previously the order was unspecified (as in Dictionary).

• When constructing an OrderedDictionary from an IEnumerable and multiple entries have the same key, an exception is now thrown instead of keeping the last entry.

• Core Metaplay parts of PlayerModel have been split into a base class called PlayerModelBase.

  • This mostly involved moving a bunch of fields to the base.
  • Some methods in PlayerModel were renamed: for example, PlayerModel.Tick() is now called PlayerModel.GameTick().
  • To maintain protocol compatibility between release-10 servers pre-release-10 clients, a MetaMembersOrderKludge attribute was added on PlayerModel. You can remove this, but doing so will break protocol compatibility and require clients to be updated to the latest version.

• In-app purchases now support recording the actual resolved contents at claim time, for customer service purposes. See Getting Started with In-App Purchases, section Recording Resolved Purchase Contents.

• In-app purchases now support dynamic purchase rewards, for features such as special offers. See Getting Started with In-App Purchases, section Dynamic-Content Purchases.

Migrations

• The GameConfig building and parsing system has been re-written from the ground up to be compatible with binary format (faster serialization with less garbage) and more robust, powerful, and flexible parsing features.
  • No action required, all old code still works. If you wish to tap into the new system, please contact us for guidance on how to migrate over.
• The MetaActionResult type is now a class, making it possible to attach more complex data to the results.
  • No action required. All existing ActionResults have been converted.
• The iteration order of the items in GameConfigLibrary is now well-specified, whereas previously it was whatever order the underlying Dictionary provided.
  • We've done our best to check that the existing code is not affected, but if you suspect your existing code might rely on the previous unspecified order, it's worthwhile to check.
• OrderedDictionary now throws when constructed from an IEnumerable that contains duplicate keys.
  • We've done our best to check that existing code is not affected, but if you suspect this might happen in your code, it's worthwhile to check and fix it.
• The locally-run server now stores Game Config archives to Server/Game.Server/bin/PublicBlobStorage/GameConfig by default, instead of Server/Game.Server/bin/GameConfigStorage.
  • If you wish to retain your current local server's Game Config storage, you'll need to move the GameConfigStorage folder under PublicBlobStorage and name it GameConfig.
• A database migration has been added to increase the length limit of the primary key of the InAppPurchases database table from varchar(160) to varchar(512).
  • No action needed, but be aware that when first deploying a release 10 backend into an existing environment, the database migration may take some minutes.

Change Log

Added

• SDK: Support for dynamic-content IAPs, where the content of a purchase is decided at runtime. Can be used e.g. for dynamic shop offers.
• SDK: Support recording the resolved contents of an in-app purchase, so that they're remembered for customer support purposes even if IAP configs later change.
• SDK: Keep current session's device id as a transient member in PlayerModel.
• SDK: MetaplaySDKBehavior now shows connection status and tools to simulate bad connections in Unity Editor.
• SDK: Ensure that client-driven PlayerModel.CurrentTime stays within accepted bounds from server wall clock (configurable via PlayerOptions.ClientTimeMaxBehind and ClientTimeMaxAhead).
• SDK: Server support for validating Sign in with Apple and Google Sign-In social login claims.
• SDK: Support associating each Firebase Messaging token with a specific device, allowing to properly avoid extraneous notifications after detaching a device from an account.
• SDK: Notification campaigns now collect more Firebase error messages besides just MessagingErrorCode to better help diagnose configuration problems.
• SDK: New server RuntimeOptions system with Options.xxx.yaml, hot-loading, classes defined locally, and Runtime Options page on dashboard.
• SDK: Notification campaigns now clean up unregistered Firebase messaging tokens.
• SDK: Add EntitySynchronize, a new EntityAsk-like communication primitive that allows arbitrary number of messages to be exchanged in both directions.
• SDK: Player IP geolocation using MaxMind's GeoLite2 Country database. PlayerModel.LastKnownLocation indicates the country of the latest login. Disabled by default.
• SDK: EntityActor.ExecuteOnActorContextAsync method for enqueuing operations on actor context.
• SDK: Support new HandlePubSubMessage(EntitySubscriber, Message), HandlePubSubMessage(EntitySubscription, Message) handlers in entity actors for handling subscription and subscriber messages. If new handlers are not defined, the normal HandleMessage and OnUnknownMessage handlers are used as previously.
• SDK: Support a binary storage format for GameConfigs.
• SDK: Support a binary storage format for localization configs, and use it by default instead of the legacy csv.
• SDK: SpreadsheetParser utility for parsing config sheets in an extensible manner.
• SDK: Types in MetaSchedule.cs for dealing with recurring calendar schedules, and a SpreadsheetParserPass for parsing them.
• SDK: Utilities for "activables", i.e. game logic items that involve time-based activation, expiration, and player segment targeting. Intended to be a component in liveops features such as special offers and events.
• SDK: Version compatibility checks for infrastructure and Helm chart versions.
• SDK: Add PlatformOptions.EnableAppleAuthentication and .EnableGoogleAuthentication flags that can be disabled to avoid contacting the relevant servers. Useful for deploying the server in areas where connections to Apple/Google servers can't be established (eg, China).
• SDK: Server now logs the client-sent game version (Application.version from Unity) for each connection, and stores it in the player's login history. The version from the player's first login is also stored in PlayerModel.Stats.
• SDK: Add metrics about database scan jobs.
• SDK: Players list API (/api/players) now reports player deserialization errors in the response, instead of filtering out the erroneous players.
• Dashboard: Cluster sharding configuration is now shown on the Environment tab.
• Dashboard: Player Incidents now have their own tab.
• Dashboard: Added a customizable game icon to the top left corner.
• Dashboard: Alternative visual style in production environments.
• Dashboard: Ability to assume different user roles for testing Dashboard permissions.
• Dashboard: Added audit logging for actions that are performed through the Dashboard.
• Dashboard: Player incidents can now be viewed by type.
• Reference project: Added connection health indicator (shown when connection is in unhealthy state).
• Reference project: "Special offers" example feature using the new utilities for dynamic-content IAPs, calendar schedules, player segmentation, and activables.

Changed

• SDK: Upgrade to .NET 5.0.4.
• SDK: Upgrade to Akka.NET v1.4.16, which significantly improves networking performance for Akka.Remote and reduces idle CPU usage.
• SDK: Serializer now supports Nullable versions of primitives, for example int?.
• SDK: CsvReader now checks that each cell is fully consumed by its parser, and throws if it's not. This guards against buggy parsers and typos in configs. This is a potentially breaking change.
• SDK: The constructor OrderedDictionary(IEnumerable<KeyValuePair<TKey, TValue>>) now throws if the enumerable contains multiple key-value mappings with the same key, instead of keeping the last one.
• SDK: Game Config storage options are replaced by a general-purpose BlobStorageOptions, supporting also a separate private S3 bucket in addition to the public CDN S3 bucket.
• SDK: Clean up server application start sequence.
• SDK: Roles and permissions overhauled and now managed through Options.xxx.yaml.
• SDK: Server now initializes Serilog before anything else so it can always be used. It is re-initialized with proper configuration after it has been parsed.
• SDK: TransientError.Unknown has been removed and replaced with TransientError.TlsError that contains more information of the TLS handshake failure. Incorrect message order in the login sequence is now a SessionError.
• SDK: Moved MasterDatabaseVersion into DatabaseOptions.MasterVersion. Add NukeOnVersionMismatch (defaults to false) for extra safety to protect against accidental resets.
• SDK: Server now enforces size limits also for the uncompressed packets and incident reports received from the client, not just compressed.
• SDK: Increased the MaxStringSize and MaxByteArraySize deserialization limits to 64MB.
• SDK: Refactored functionality of GameConfigBuilder to have it less strongly tied to Unity.
• SDK: GameConfigLibrary now holds the items in an OrderedDictionary (instead of Dictionary) in the source configuration order.
• SDK: The UTC offset range in PlayerTimeZoneInfo was changed from -12h...14h to -18h...18h for consistency with Noda Time.
• SDK: PlayerModel.TimeZoneInfo now persistently stores the latest info, instead of only being available during a session.
• SDK: MetaActionResult is now a class, so it's possible to include richer information about some errors. Common errors are declared as static readonly members, to avoid allocation overhead.
• SDK: All server and botclient configuration has been migrated to the new RuntimeOptions system, including switch to Options.xx.yaml (from old Config.xx.json). The Options are all visible in dashboard under 'Runtime Options' tab for easy viewing, including the source where they are defined.
• SDK: EntityId.Kind no longer throws even on invalid or illegal values, but returns an EntityKind with .IsValid == false. EntityId.IsValid now also checks for the EntityKind.IsValid as well. This makes the message routing code more robust against malformed EntityIds.
• SDK: GameConfigBuilder has been refactored: content-specific steps are now part of MainGameConfig, and GameConfigBuilder is mainly a simple Unity stub.
• SDK: GameConfigArchives are now persisted in binary by default. Old csv/json can still be used where needed, but migrating to binary format is recommended.
• SDK: MainGameConfig is now persisted as single .mpa archive file by default. Old multi-file archives can still be used.
• SDK: PlayerModel's SDK-side parts are now separated into a PlayerModelBase class, which the game-specific PlayerModel inherits.
• Dashboard: Sidebar Vue file refactored with a new SidebarNavGroupItem component for better legibility and easier maintenance
• Dashboard: Display large numbers as abbreviated (eg, 1.24M) to make them more readable.
• Dashboard: Player event log displays event timestamps based on game logic time by default, instead of server's real time. This is consistent with the current behavior of the IAP history display.

Fixed

• SDK: MetaTime.ToString() now properly pads numbers and uses dashes to separate date, eg: 2020-12-15 03:00:02.468 Z.
• SDK: UnhandledExceptionError stack traces are now limited to 8kB.
• SDK: Fixed integer overflow in MetaDuration.FromSeconds(F64) when duration was longer than 25 days.
• SDK: Fixed issue where SDK reported Unhealthy network state even after the unrelying network returned to good health.
• SDK: Don't allow [MetaSerializableDerived] on abstract classes.
• SDK: Don't try to upload incident reports when in Offline Mode.
• SDK: Fix duplicate call to EntityActor.Initialize() for PersistedEntityActors.
• SDK: Increase timeout in database re-sharding query to avoid problems with large data sets.
• SDK: Fix some potential race conditions in server initialization.
• SDK: Notification campaigns: Avoid sending duplicate notifications to devices that have switched to a different account using social authentication.
• SDK: Fix an exception being thrown when purging old player event segments (due to accessing Akka's Context static variable).
• SDK: Check for correct game magic in network diagnostic game server probe when generating a report.
• SDK: EntityActor.ExecuteInBackground() now executes the operation on the current Actor context (assuming it's valid).
• SDK: Fix case where PlayerId None could be persisted in database by SocialAuthenticateResolveConflict when no pending conflict exists.
• SDK: Improve server robustness against invalid EntityIds in entity messaging and authentication.
• SDK: Fix race bug in GameConfigLibrary's type registration. Relevant for when multiple BotClients are started in quick succession.
• SDK: Client now more accurately follows the configured session resumption timeout, instead of waiting for a transport connection attempt to fail on its own.
• SDK: Fixed player event log http API when events contain game config references.
• SDK: ShardyDatabase.InsertOrIgnoreAsync() no longer throws ItemAlreadyExistsException when the item is already in database (fixes errors being logged from persisting player incident duplicates).
• SDK: Fixed various cases of formatting and string comparison so that they don't depend on the current culture.
• SDK: PersistedInAppPurchase.TransactionId now supports ids up to length 512 instead of 160. This fixes duplicate purchase detection for transaction ids longer than 160.
• SDK: Players list API (/api/players) now catches all exception types coming from deserialization, not just MetaSerializationException.
• SDK: Fix case where Json-to-S3 Analytics sink would report an error and drop overflowing events if write buffer got more events than could fit into a single S3-written blob (by default 100k events).
• Reference project: For players with PlayerModel.Language == null, set it to default in PlayerActor.RestoreFromPersisted() to ensure players always have a language set.
• Reference project: Producers are now updated properly when player returns to game after being offline.
• Dashboard: Fixed issues with API polling where the polling was not getting cancelled. Added new class to encapsulate correct polling behaviour