Highlights

• New preview feature: Experiments adds the ability to perform split tests of different Game Configs variants with your live players. Use your Game Configs to define the variants to be tested and easily manage ongoing tests from the LiveOps Dashboard. Documentation for this feature is still ongoing, so talk to us to get started!

• Major improvement: The Game Configs System v2 now supports a build history with diff views, manual publishing, and rollbacks from the LiveOps Dashboard, server-only data, partial builds, Game Config variants, and more. Updating the documentation for this feature is still ongoing, so talk to us if you are interested in the details!

Breaking Changes

• LiveOps Dashboard Node.js version updated to 16.x and NPM to 7.x. All breaking changes were already resolved in the previous Metaplay release.
  • Action required: Please update your local Node.js to 16 to avoid compatibility warnings when running npm install. Older Node.js versions will still work, despite the warning.
• The Game Config System has been significantly overhauled which makes the Game Configs incompatible with previous versions and requires a synchronized client and server update*.*
  • Action required: Bump the game's LogicVersion to force the synchronized update.
• MainGameConfig has been renamed to SharedGameConfig to emphasize that it is the data available to both the client and the server, and a ServerGameConfig was added that is only visible to the server.
  • No action required: All projects have been migrated to use the new name.

Notable Under-the-Hood Changes

• Upgraded to .NET 5.0.9, and Entity Framework Core to v5.0.9, now that the Pomelo project officially supports it.

• Upgraded Akka.NET to v1.4.23 which brings some performance improvements.

• [EntityAskHandler] methods can now return the response value instead of using ReplyToAsk() to simplify the code. For example:

  // New simple style:
  public PlayerStateResponse HandlePlayerStateRequest(PlayerStateRequest _)
  {
    return CreatePlayerStateResponse();
  }
  
  // Old style (still valid):
  public void HandlePlayerStateRequest(EntityAsk ask, PlayerStateRequest _)
  {
    ReplyToAsk(ask, CreatePlayerStateResponse());
  }

• EntityAsk failures now lead to an InvalidEntityAsk exception being thrown at the caller instead of timing out. This happens for both a) the EntityAsk handler itself throwing an unhandled exception, or b) if the Entity Actor fails to spawn to respond to an EntityAsk. This way, the error messages are clearer and they occur immediately instead of with a 10 second delay from the timeout.

• The AdminApiActor now handles remote EntityAsks in a more robust manner: failing EntityAsks no longer cause AdminApiActor to fail. Also, multiple EntityAsks can be performed in parallel, when previously they were executed sequentially.

• After players have reached their scheduled deletion time, a server job deletes the players from the database. This job used to run every 24 hours, but there was no way to determine the time exactly. This led to performance spikes at unexpected times for some customers. A new configuration option System.PlayerDeletionSweepTimeOfDay has been added to allow you to decide exactly when this job starts. By default, this time is set to 2AM UTC.

• The JSON-to-S3 analytics event sink is now configurable via the Runtime Options system. See the Built-in JSON-to-S3 Sink section of Streaming Analytics Events to External Storage for more details.

• Database latency metrics no longer include the time spent in server throttle queue, and now only measure the operation latency. This avoids apparent latency spikes when a large number of background operations were enqueued. Throttle queue size can be observed via meta_db_throttle_ops_* metrics, for which a widget has been added in the default Grafana dashboard.

• Player maximum session length can be now defined with Session:MaximumSessionLength Runtime Option. If maximum length is defined, a player session exceeding this limit is terminated from the server. This can be used to limit unnaturally long sessions. This can also be used to set an upper time bound for a Game Config update to become active for all players since the config updates are applied only on session (re-)start.

• An activable (such as a Shop Offer) item being removed from the Game Config no longer causes a player state deserialization failure when that player state contains a reference to the activable. Instead, the reference is ignored, but still serialized back when persisting the player, so that no data is lost in case the removal was accidental.

• Activables (such as Shop Offers) are now able to react to lifetime configuration changes as soon as the Game Config takes effect, even if an activation is already ongoing. This is controlled by the new AllowActivationAdjustment parameter in MetaActivableParams. See section Additional MetaActivableParams in Getting Started with In-Game Offers for more details.

• Fixed the PlayerSegmentSizeEstimator to not invoke lots of database requests at the same time. This eliminates the false spikes in the database access latency graph on Grafana. It also amortizes the CPU usage over time.

• Game Config ID aliases can be entered in Google Sheets using a special column named /Aliases that can be used to specify an alternative ID for a row.

Notable LiveOps Dashboard Changes

• Server-side errors are now reported properly on the dashboard instead of giving a vague 5xx error. For example, when viewing a player that fails to deserialize, a copy-pasteable error message is shown.

• Audit log events now include IP address and country of origin. You can also search for events by country or IP address. Please note that this feature might not work correctly for all deployments - the reported IP address may be that of the load balancer instead of the end user. This will be fixed with an infrastructure update in R15.

• Offers and Events now include statistics about player participation and conversion.

• Broadcasts and Notification Campaigns now have a confirmation dialog to prevent accidental deletion.

Version Compatibility

Infrastructure and Helm chart compatibilities for this release:

• Minimum version requirements
  • Requires infra-modules version v0.1.3 or later for infrastructure
  • Requires metaplay-gameserver Helm chart version 0.2.0 or later for deployment
• Suggested versions
  • Recommended infra-modules version v0.1.5 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.2.2 or later for deployment

Change Log

Added

• SDK: Initial support for A/B tests, with the ability to define the content changes via the GameConfigs, ability to configure the Experiments from the dashboard, and all the scaffolding to assign players into the Experiments and Variants.
• SDK: History of uploaded GameConfigs in the dashboard, including the ability to diff between the versions and choose the currently active one.
• SDK: ServerGameConfig that contains GameConfig data that is available only on the server.
• SDK: GameConfigs now include Patches alongside the baseline data. Patches can be used to override the baseline contents and are used by the A/B tests.
• SDK: GameConfig archives can now be partially built, meaning that some parts of the archive are fetched from the server (and remain untouched) while other parts are built from the source data (eg, Google Sheets).
• SDK: Added a convenience PlayerId property to GuildMemberBase for conveniently getting the member's player id.
• SDK: [EntityAskHandler] methods now have the option of returning the value to automatically have it routed to the caller (previously, ReplyToAsk() had to be used). In that case, the method may not take the EntityAsk as an argument to avoid accidental double-replies.
• SDK: [MetaOnDeserialized] methods now can optionally take a MetaOnDeserializedParams parameter, which contains some deserialization context such as the IGameConfigDataResolver.
• SDK: Added support to MetaActivables for removing activables' config items without breaking the deserialization of player states containing those activables. Enabling this requires minor changes to the game-specific classes inheriting MetaActivableState.
• SDK: Ongoing activations in players' existing MetaActivable states can be configured to be affected by config changes. For example, changing a lifetime parameter can adjust the end time of ongoing activations, instead of the lifetime being fixed when the activation starts.
• SDK: In development mode, exception stack traces during login (for example due to deserialization error) are now delivered to client via Message string in TransientError.SessionError.
• SDK: Added EntityAskError serializable exception type for communicating controlled error situations from EntityAskHandler functions. These exceptions will be thrown at the remote callsite using the original type and they won't cause the handling actor to be terminated.
• SDK: Make SessionToken available in PlayerModel during a session. Include the token in core connection analytics events.
• SDK: Added MetaGuid type, which is a time-ordered globally unique identifier type.
• SDK: Added support for serializing GameConfigLibrary ID aliases in the GameConfig archive.
• SDK: GameConfig ID aliases can be entered in Google Sheets using a special "/Aliases" column that lists alternative IDs for a row.
• SDK: New BackgroundTaskActor allows running various one-shot jobs on the server.
• Dashboard: CS audit log events now show IP address and country of origin, and can be searched by IP or country.
• Dashboard: Added MetaClipboardCopy component to make copying text to the clipboard easier and more consistent.
• Dashboard: Added MetaCountryCode component to simplify display of country flags and names.
• Dashboard: Added conversion % of activations vs consumes to the activable details page (for example: events and offers).
• Dashboard: When viewing a Player whose Actor crashes (eg, due to broken migration code), a useful error message is shown.
• Server: Added optional maximum session length limit option Session:MaximumSessionLength.

Changed

• SDK: Upgrade to .NET 5.0.9 (SDK 5.0.400).
• SDK: Upgrade dependencies, mainly EFCore 5.0.9, Pomelo 5.0.2, and Akka 1.4.25.
• SDK: Renamed old MainGameConfig to SharedGameConfig to emphasize that it's the part of GameConfigs that is shared between the client and the server.
• SDK: GameConfigBuilder scaffolding has been significantly upgraded, to add support for ServerGameConfigs, partial builds, building on the server, extract patch data for A/B tests, and to make integration to Unity projects simpler.
• SDK: Errors during the handling of EntityAsks are now returned back to the caller as EntityAskError exceptions, including the error type, message, and stack trace of what went wrong.
• SDK: Serializing MetaDuration as JSON now uses the format 'd.hh:mm:ss.FFFFFFF' to make it more easily consumable in the dashboard and analytics event pipelines.
• SDK: Overwriting entity event log segments no longer causes a (benign) error message.
• SDK: Tweaked player deletion sweep to make it less resource hungry.
• SDK: Player deletion sweep now happens at a configurable time of the day so that it is more predictable.
• SDK: Checksum mismatch handling no longer rolls back model state in time. This avoids failing potential sanity or consistency checks when rolled back state catches up with the present again.
• SDK: The JSON/S3 analytics event sink can now be configured with Runtime Options.
• SDK: Moved BlobStorageOptions to CloudCore, so it can be used by other systems in CloudCore (eg, analytics event sinks).
• SDK: Replaced the boolean ServerCommitIdMustMatch with an enum ClientServerCommitIdCheckRule.
• SDK: As part of the new AdminApi entrypoints for dealing with GameConfigs, the existing publish entrypoint paths have changed.
• SDK: The GoogleSheetFetcher utility has been moved to the Metaplay SDK Core to pave way for running GameConfig builds tasks on server.
• SDK: On ModelJournal desync where the current Model is no longer deterministically reachable from the latest checkpoint (non-deterministic actions), the current version is no longer reconstructed from action log. Instead, latest snapshot is synchronized to the current version, when possible.
• Dashboard: Project lockfile updated to Node 16.x and NPM 7.x.
• Dashboard: Docker builds now use Node 16.x (node:16-alpine) base image.
• Dashboard: Cypress test runner updated to 8.2.
• Dashboard: Now reports more detailed information about API errors to the user.
• Dashboard: Activable detail pages now include uptake and total uptake.
• Dashboard: Added confirmation modals when deleting Broadcasts and Notifications.
• Dashboard: Show humanized usernames in audit logs for auth_not_enabled and no_id.
• Dashboard: The previously fire'n'forget MetaplayBaseController.TellEntityAsync() now uses EntityAsk pattern to wait for a success response or an error that may have occurred during the handling of the message.
• Dashboard: Show any errors that happened while executing the various HTTP requests into the server.
• Dashboard: New, mobile friendly notifications for maintenance mode and game config updates.
• Reference project: Bots now use randomized names to make them appear more realistic.
• Reference project: New EditorWindow-based GameConfig builds UI that allows specifying partial builds and overriding spreadsheet.
• BotClient: Fix CdnBaseUrl to not expect /GameConfig/ suffix, to match Unity client behavior.

Fixed

• SDK: Improve AdminApiActor stability when routing EntityAsks. EntityAsks are no longer blocking and exceptions are routed to the caller instead of crashing AdminApiActor itself.
• SDK: Fix json analytics sink failing if GZip compression was not used.
• SDK: Fix MetaDuration.ParseExactFromJson() invalid input handling.
• SDK: Fix DB latency metrics including the time in the throttle queue. This could cause DB latencies appear very high when throttled background tasks were running.
• SDK: SegmentSizeEstimator now makes its queries sequentially, to smooth out the database accesses over time, avoiding the database latency spikes that happened before.
• Dashboard: Fix 'Open Grafana' link on front page to be enabled.
• Dashboard: Fixed not being able to remove broadcast and notification localization languages
• Reference project: Fix time handling innaccuracy in producer ticking.