Highlights

• New feature: Game config compression reduces the download size of game configs by approximately 80-85%. The feature will be automatically enabled.

• New feature: Player developer privileges allow giving developers extra privileges in the production environment. Developer players can log in during maintenance mode, can execute [DevelopmentOnlyAction]s, and perform sandbox purchases on iOS. See Working with Developer Players for more information.

• New feature: Analytics event custom labels allow games to add custom data to server-side analytics events. Check out Implementing Analytics Events in Game Logic on how to add your first custom label, and see Streaming Analytics Events to External Storage for details on how these labels are written out to the external storage.

• New feature: Debug-forcing of activables is a development-time feature for bypassing the configured scheduling and targeting of activables (such as in-game events) to test their various phases. See section Force-Activating Events During Development in Implementing Config-Driven Game Events for how to access this feature.

• New feature: Player segment combinations. It is now possible to target broadcasts, notifications, and experiments to players that match multiple segment conditions. This effectively means that in addition to being able to target players who match any of the listed segments, you can now match players who only match against all.

  An example use case might be to send a broadcast to anyone that is over level 20, was last logged in from the US, and has made purchases in the game. Previously this was only possible by declaring a separate combination segment, now the combination can be declared as part of the targeting parameters.

• Streamlined feature: Banning players now prevents them from starting a game session and reports a new dedicated error code, which makes handling banned players easier on both the server and the client. No need to remember to inspect IsBanned again. See Player Banning for tips and tricks.

INFO

Comment on log4j (CVE-2021-44228 and CVE-2021-45046): We are aware of the recently disclosed issues in log4j. Metaplay backends do not utilize log4j and are not susceptible to the issues described in the CVEs. We have additionally reviewed the underlying AWS services that are being used in conjunction with our infrastructure setups and our current understanding, based on our own review and AWS's comments, is that there are no current vulnerabilities in the infrastructure services related to the CVEs either.

Please note that if you have deployed any non-Metaplay software as part of your backend, you should review whether components you may have inserted yourself are vulnerable and patch and update accordingly!

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.
• Upgraded to .NET 6.
  • Action required: Upgrade to Visual Studio 2022 or Rider 2021.3 for compatibility with .NET6.
• LiveOps Dashboard dependencies have been updated.
  • Action required: Run npm install in the dashboard project folder to refresh your local development environment before launching the dashboard project.
• The multi-node clustering topologies are now configured in Options.base.yaml using Clustering.ShardingTopologies. The old Helm values-based definitions are deprecated and no longer used.
  • No action required: All projects have been migrated to use the new system. When adding new Entity types, add them in Options.base.yaml.
• metaplay-gameserver 0.3.0 helm chart replaced experimental.gameserverIpv6Enabled parameter with service.ipv6Enabled and set it to true by default.
  • Action required: Update your chart values accordingly.
• metaplay-gameserver 0.3.0 helm chart replaced experimental.publicApiEndpoints block with publicApiEndpoints.
  • Action required: Update your chart values accordingly. The format of the block is the same as before.
• metaplay-gameserver 0.3.0 helm chart replaced admin.auth block with auth. This object can be used to configure Auth0 or more general OIDC authentication setups. When used for configuring Auth0 authentication, these values will be configured across all relevant chart-managed resources (e.g. LiveOps dashboard, Grafana, etc.) and will not require duplicating the same information across multiple configuration blocks.
  • Action required: Update your chart values accordingly.
• metaplay-gameserver 0.3.0 helm chart replaced oauth2-proxy with external-auth-server to provide authentication services to Ingress.
  • Action required: Update your chart values accordingly. external-auth-server configurations are found under auth.eas, but the defaults should work for most of the cases.
• Known issue: Node 17 currently breaks some of the LiveOps Dashboard dependencies. We will update them once the community has fixes available.
  • No action required: Continue to use the latest LTS version of Node (16.x) and all is well.
• EntityKinds are now separate to various registries based on owner and visibility. Game Entities are defined in EntityKindGame for client-and-server-visible Entities, and EntityKindCloudGame for server-only-visible Entities. Similarly, builtin Metaplay Entities are now defined in in EntityKindCore for client-and-server-visible Entities and EntityKindCloudCore for server-only-visible Entities.
  • No action required: Existing references have been updated and Game Entities are separated into the new Registries.
• MetaDefines has been removed and has been replaced by GlobalOptions. This mainly affects updating the current LogicVersion ranges, which must now be updated in GlobalOptions.cs instead.
  • No action required: Values defined in MetaDefines have been ported to GlobalOptions.
• metaplay-gameserver 0.3.0 helm chart deprecated and removed externalDns configuration block.
  • No action required: From now on, external-dns is required to be present on the cluster into which the chart is being deployed.
• metaplay-gameserver 0.3.0 helm chart deprecated and removed api configuration block.
  • No action required: From now on machine users interacting with the game server API must use the same game server admin Ingress as the LiveOps dashboard users.
• metaplay-gameserver 0.3.0 helm chart limited game server service load balancer type to only AWS NLBs.
  • No action required: This aligns with AWS's move to deprecate classic load balancers.

Notable LiveOps Dashboard Changes

• New timeline-based view of events to improve workflows for CS agents when dealing with event streams such as player events and audit logs.

  • This new component replaces event and audit log lists in many dashboard pages:

    

  • A new dedicated event timeline page shows event streams in even greater detail:

    

• The Compare Game Config Versions page now allows you to quickly and easily select any two game configs for comparison. In the main view of this page, individual difference chunks can now be collapsed to reduce noise.

Notable Under-the-Hood Changes

• Upgraded projects to .NET 6.0 (LTS), Entity Framework Core 6.0 and ASP.NET Core 6.0.
• 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.
• Further separation of userland code from the SDK core has been done, including removing most inverse dependencies from core to userland (a few still remain). This will make future Metaplay upgrades faster and safer by reducing the number of merge conflicts.
• Entity actors are now registered with the new [PersistedEntityActor] and [EphemeralEntityActor] attributes into a EntityActorRegistry. The registry is used for storing metadata such as schema versions and the types are used to persist objects into the database.
• New attributes have been introduced to register additional behavior for entity types:
  • [EntityMaintenanceRefreshJob] registers a refresh database scan job for the entity (triggerable from the dashboard).
  • [EntityMaintenanceSchemaMigratorJob] registers a schema migrator database scan job for the entity type (triggerable from the dashboard).
  • [EntityMaintenanceJob(..)] registers a custom maintenance database scan job for the entity type (triggerable from the dashboard).
  • [EntityArchiveImporterExporter(..)] registers entity archive import/export functionality for the entity type. These are invoked by the export and overwrite player state buttons in the dashboard.
• Multiple improvements to the incident report handling:
  • Game config version and experiment memberships are now included in the reports.
  • Reports collected during a session are more robustly uploaded during the session. Earlier, reports would sometimes only upload on the next session.
  • Uploading only happens 10 seconds after establishing a connection to the server.
  • Network errors no longer contain null bytes in the exception message. These were caused by Unity not sanitizing its inputs properly.
• Fixed database re-sharding to work with items that didn't have a [PrimaryKey] member. It is now possible to do re-sharding again. The operation can still take a lot of time with big databases, so please talk to us if you want to do a re-sharding operation in production.
• Upgraded AWS EKS version to 1.20. It is advisable to carry out AWS EKS updates through the AWS web console or CLI and update the cluster first to 1.20 and then run updates through Terraform apply. This will minimize the required maintenance break when updating the infrastructure (updating EKS can be done while the rest of the game backend remains up).

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.7 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.3.0 or later for deployment

Change Log

Added

• SDK: Introduce EntityActorRegistry which keeps metadata about all EntityActors and can be used to query it.
• SDK: Added [JsonSerializeNullCollectionAsEmpty] attribute to allow serializing null arrays and dictionaries as [] and {} in JSON.
• SDK: For server-side analytics, added support for setting custom labels (key-value pairs) to all emitted analytics events of an Entity.
• SDK: The connection fails with a new TerminalError.PlayerIsBanned error if attempting to log in with a player that is banned. Ongoing sessions are terminated with a new SessionForceTerminateReason.PlayerBanned reason. In LifecycleDelegate both are exposed as ConnectionLostReason.PlayerIsBanned.
• SDK: Added a client-side IAPManager for managing the flow of IAPs between the game, Metaplay, and Unity IAP. Previously, IAPManager existed in the Idler reference project.
• SDK: Development functionality for forcing activables (e.g. in-game events) into a specific phase (e.g. active) for individual players, for testing purposes.
• SDK: Mechanism for registering custom database maintenance jobs for PersistedEntityActors using the [EntityMaintenanceJob(..)] attribute.
• SDK: GameConfigs are automatically compressed by server before delivering them to clients. This is backwards compatible. Compression can be controlled with ContentDelivery Runtime Option.
• SDK: Added an ExtendableEvent utility built on top of activables, for implementing in-game events whose activations can be extended while in review phase.
• SDK: Include client-facing game config version and experiment memberships in player incident reports.
• SDK: Added the possibility of marking a player as a developer, enabling them to log in during maintenance mode, execute development actions in prodcution environments and validate iOS sandbox IAPs.
• SDK: Added option of targeting an intersection of segments (must match ALL segments) in addition to previous behaviour of union (must match ANY segment) in broadcasts, notifications and experiments.
• SDK: Preliminary support for triggering broadcasts based on gameplay (analytics) events. Not enabled in dashboard by default.
• Dashboard: Added ability to view the differences between arbitrary game configs on the game configs diff page.
• Dashboard: Difference chunks on the game config diff page can now be collapsed to reduce noise.

Changed

• SDK: Upgraded to .NET 6 and C# 10.0, ASP.NET 6, and EFCore 6.
• SDK: Switched to using [Index] attribute for the database index definitions.
• SDK: Split core-specific parts from GameDbContext into MetaDbContext<TPersistedPlayer, TPersistedGuild>.
• SDK: Move PersistedPlayerSearch into core where it belongs.
• SDK: Move core-required members from PersistedPlayer to PersistedPlayerBase.
• SDK: Move most of ServerMain into SDK core class ServerMainBase.
• SDK: When parsing multi-column arrays or lists in GameConfigs (noted with [ColumnNames] in brackets), fill empty cells between non-empty cells by parsing the empty string to the correct type. Empty cells at the end of collections are still ignored.
• SDK: Missing translation texts are now represented as "#missing#{TranslationId}" to distinguish missing translations from untranslated text.
• SDK: Removed PlayerActor.CreatePlayerStateResponse() as it's no longer needed.
• SDK: Support virtual database items in the core to allow untangling SDK code from userland when accessing PersistedPlayers or PersistedGuilds.
• SDK: Removed all CreateDataResolver() methods -- use the relevant ISharedGameConfig instead.
• SDK: Moved PlayerActor.RegisterPlayerAsActive() into PlayerActorBase.
• SDK: Introduced PlayerActor.CreatePersisted() for creating the game-specific PersistedPlayer object.
• SDK: Log the AdminApi request query strings as well.
• SDK: All EntityActor types must now have either [PersistedEntityActor] or [EphemeralEntityActor] attribute.
• SDK: PersistedEntityActor schema version is now defined via [PersistedEntityAttribute(..)].
• SDK: Segment targeting for broadcasts, notifications and experiments now uses a PlayerCondition to be able to express segment and property requirement combinations.
• SDK: On Client, Connection.Reconnect() emits DisconnectedFromServer and processes its handler synchronously before starting to open the new connection.
• SDK: Banning a player now prevents logging in rather than executing actions.
• SDK: Configure deployment sharding topology via ClusteringOptions.ShardingTopologies and TopologyId.
• SDK: Remove some boilerplate from GameDbContext and remove DatabaseBackendXyz dependency on GameDbContext.
• SDK: EntityRefresherUtil and EntitySchemaMigratorUtil now query EntityActorRegistry instead of including metadata about EntityKinds.
• SDK: Entities eligible for Archive Importing and Exporting are marked by setting [EntityArchiveImporterExporter] for Actor. Player and Guild Actor are eligible automatically with the default Import & Export handlers.
• SDK: Entity Id remapping logic (during EntityArchive import) is moved from ImportEntityHandler into (Player|Guild|*)Model.RemapEntityIdsAsync.
• SDK: Game-specific AdminApi GamePermissions must now have [AdminApiPermissionRegistry].
• SDK: Replaced the statically-referred game-specific MetaDefines by a MetaplayCoreOptions which the SDK discovers by reflection at initialization time.
• SDK: Entities eligible for Refresh and Schema Migration scan jobs are marked by setting [EntityMaintenanceRefreshJob] and [EntityMaintenanceSchemaMigratorJob] for Actor. Player and Guild Actor are eligible automatically.
• SDK: Register player deletion maintenance job with the new generic maintenance job mechanism: [EntityMaintenanceJob("Delete", typeof(ScheduledPlayerDeletionJobSpec))].
• SDK: Moved most boilerplate of an empty SessionActor to SessionActorBase.
• SDK: Make AdminApi request logging configurable: by default, only log requests that take a long time when running server locally to quiet down spammy logging.
• SDK: Renamed PlayerActor.OnNewOwnerSubscriber and OnOwnerSubscriberLost to OnNewOwnerSession and OnOwnerSessionEnded. OnOwnerSessionEnded is now also called when session ends due to player being kicked.
• SDK: Removed GuildActor.ValidateGuildCreationAsync and replaced it with overridable PlayerActor.ValidateGuildCreationAsync.
• SDK: Renamed ServerAction into UnsynchronizedServerAction to better describe its behavior.
• SDK: Network threads no longer synchronously call Unity log handlers. Low-level network logs are instead buffered and flushed later on Unity thread.
• SDK: ConfigArchiveEntry.Bytes is now accessed via ConfigArchiveEntry.Uncompress().
• SDK: IJournalModelAdapter (and the game-side implementations like PlayerAdapter) has been removed and its responsibilities refactored to various places.
• SDK: GuildModelBase<...> now implements IGuildModelBase and some of its methods. Accordingly, various methods in GuildModel are now defined as overrides instead of direct interface method implementations.
• SDK: Make offers in offer groups "sticky" by default: during an offer group's activation, an offer won't become unavailable if its offer-specific conditions become unfulfilled.
• SDK: Changed how connection rejection during maintenance mode works to allow for checking if a player is a developer first. This deprecates ProtocolStatus.InMaintenance.
• AdminApi: Moved time consuming fetching of database item counts from /status endpoint to its own endpoint.
• AdminApi: [Consumes("application/json")] is now applied on per-endpoint basis as ASP.NET 6 no longer matched any of the routes without explicit specifying the 'Content-Type: application/json' header, even where no content exists.
• Dashboard: Major overhaul of how time-based events (eg: player actions, audit logs, etc.) are shown.
• Dashboard: Cypress tests now fail if error or warning messages are printed out to the console while the test is running.

Fixed

• SDK: Game-config-build-time debug validation of MetaRefs: Ignore indexers and getterless properties in the object tree traversal.
• SDK: When parsing enum-typed config keys, produce properly enum-typed objects instead of integers.
• SDK: In Unity editor, don't report a player incident when the connection is closed due to exiting play mode.
• SDK: Add check for GameConfigLibrary keys producing non-unique values from ToString(), which causes the duplicates to not show properly on the dashboard.
• SDK: Fix SDK initialization when a kind of activable is missing its MetaActivableSet type.
• SDK: Unity network error messages sometimes contain null bytes, which ended up in incident reports. They are now trimmed when generating the report.
• SDK: Replace deprecated crypto primitives with the .NET6 recommended SHA256.Create() etc., and RandomNumberGenerator.GetBytes().
• SDK: More robust checks to not allowed PlayerActor or GuildActor to spawn for non-existent entities. At least an empty state must exist in the database.
• SDK: When JSON-serializing entity event log or audit log events, tolerate exceptions thrown from the EventDescription property getter.
• 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).
• SDK: Database re-sharding fixed for items without a [PrimaryKey].
• SDK: Fixed a responsiveness bug with database scan workers when work ticks took a longer time than the desired tick interval. This would sometimes manifest as the notification campaign system becoming temporarily unavailable after cancelling a campaign.
• SDK: Small miscellaneous fixes to incident report collecting & uploading: better amortization of uploads over time, better buffering of report headers in client, and global throttle for collecting all report types.
• SDK: Use shared HttpClient when generator network diagnostics reports, to reduce the chances of exceptions in its Dispose() method (caused by a known bug in Mono version used by Unity, should be innocuous).
• Dashboard: Fixed issue with MetaListCard sometimes showing an empty page when searching or applying filters on a list that spans multiple pages.
• Dashboard: Fix visualization of network latencies in incident reports.
• Dashboard: Developer mode toggle is now synced across browser tabs.