Highlights

• Game clients can now determine there is an ongoing maintenance even if the server is shut down. If the backend is orderly shut down and no maintenance was scheduled, it is automatically reported as a maintenance mode to the clients. For more information, have a look at Maintenance Mode
• The searching by name for Players and Guilds has been made significantly faster: the new implementation utilizes an SQL index where the names are stored, starting at each word boundary. This allows queries to finish in milliseconds even for large database sizes.
• File-based entity export & import. You can now work with entity archives as files in addition to copy/pasting strings. This significantly improves browser performance for very large archives.

• New maintenance jobs feature. You can trigger this new type of database scan jobs to easily wake up players to trigger migrations and other player state updates! For more information, have a look at Database Scan Jobs

• A priority system for database scan jobs ensures that urgent jobs (such as notification campaigns) are not delayed due to ongoing non-urgent jobs (such as maintenance jobs).
• New broadcasts feature. You can schedule and target automated mass in-game mail campaigns to your player base. For more information, have a look at Managing Broadcasts.

• Quality-of-life improvements to the player details page. The new layout is faster to work with, takes less space on small screens and the new search utilities make it much easier to quickly find that one piece of information you are looking for!

Using the new filters menu to hide all 101 resource events.

• Added support for Facebook Login. Game Backend can now validate and process Social Authentication request for Facebook Login tokens. By integrating Facebook SDK into the game client, you may allow users to log in to the game with their Facebook Accounts. For details, see Getting Started with Social Logins.
• Added support for Game Server API endpoints to be located at paths other than /api. For instance, endpoints that are intended to be called by external services can be rooted under /webhook. The different root paths can then have different access management controls applied to them at the infra level. This makes it possible to expose specific sets of API endpoints to external services without having to expose all endpoints.
  • For details on how to operationally expose these endpoints as part of game server deployments using the metaplay-gameserver Helm chart, please refer to the chart README. Support for this requires metaplay-gameserver Helm chart version 0.2.2 or later.

Breaking Changes

• Player (and guild) name search implementations have been implemented with a custom SQL table and an efficient index. The new search tables must be populated by waking up all the player (and guild) actors. This is done with a Database Scan Job. The maintenance job is limited to processing about 160 entities/second to avoid impacting other database operations significantly, so it may take multiple days to complete for large databases.
  • If your game isn't using names, no action needs to be taken.
  • Invoke a 'Refresher' Database Scan Job for the relevant entity type, which wakes up the entities.
  • Alternatively, the entity's SchemaVersion can be bumped and a 'Schema Migrator' job may be run to achieve the same effect. Using this method gives better statistics about the migration.
• Deployment Config CDN Base URL format has been changed. The URL no longer contains the /GameConfig suffix. If the URL was previously, https://mygame-env-assets.p1.metaplay.io/GameConfig, it should now be https://mygame-env-assets.p1.metaplay.io/. For local server, the url syntax is different and the CDN url should now have /api/cdnEmulator/ path. If your localhost CDN url was previously http://localhost:5000/api/gameConfig, it should now be http://localhost:5000/api/cdnEmulator/. Note that in addition to path change, the new URLs always end with a /.
  • The Unity client and BotClient have been updated, so no action should be needed. If you have reference to the CDN elsewhere, those need to be updated.

Under-the-Hood Highlights

• New meta-list-card dashboard utility component. You can use it to very quickly add usability-friendly lists to the dashboard for things like player inventories and get all our new search utilities and paging for free!
• New meta-collapse dashboard utility component. You can use it to add consistent-looking collapsible sections to pages showing a lot of information at once make the page too busy.
• Updated time-ago dashboard utility component to more consistently update in real-time and show relevant tooltips about various time stamps around the dashboard.
• New system for maintaining estimates of player segment sizes by periodically sampling the database.
• Forms for generating in-game mail and broadcasts in dashboard have been broken down to components MessageAudienceFormand LocalizedMessageContentForm in addition to the existing AttachmentPickerForm for reusability and customization purposes.
• The serialized forms of PlayerModel (converted into human-readable format) are now logged when a Desync happens. This helps debug tricky issues where the PlayerModels end up identical. For example, serializing members in a different order can only be seen in the binary-serialized data.
• Command line argument syntax is now strictly validated. Invalid format and unrecognized arguments are now an error instead of being silently ignored. Unrecognized argument from other Runtime Option sources, such as yaml files and Environment Variables, cause warnings.
• New command line aliases added: -LogLevel=Debug|Information|Warning|Error, -EnableMetrics=true|false, -RemotingPort=<port>, -ShardingConfig="path/to/clusterConfig.json".
• Performance improvements to the list of recent incident reports on the Dashboard's Overview page keeps it responsive even under heavy load.
• Some frequent but low-value Debug log events have been silenced in order to make using Debug log level scale better to higher player volumes.
• When the server receives malformed data where valid game protocol data is expected, errors are no longer logged if the malformed data is of a well-known kind, like an HTTP request. This reduces log errors on production servers that receive occasional request attempts not originating from a game client.
• Fixed: The serializer now detects private members defined in base classes. Previously, it silently ignored them by mistake.
• Local server now force terminates with a single Ctrl-C. Previously server required two Ctrl-C signals.
• New Audit Log event types for Broadcasts and Notifications, to allow associating events related to a given entity

Migrations

• The player event log entries are no longer visualized using custom code in PlayerGameEventLogEntry.vue. Instead, abstract EventTitle and EventDescription properties have been added to PlayerEventLogEntryPayload; the dashboard gets the event's title and description from those properties. This simplifies the implementation of new event log entry types.
  • No action required for existing event log entry types. We have migrated them to use the EventTitle and EventDescription properties, and removed PlayerGameEventLogEntry.vue.

Version Compatibility

Infrastructure and Helm chart compatibilities for this release:

• Minimum version requirements
  • Requires infra-modules version 0.1.2 or later for infrastructure
  • Requires metaplay-gameserver Helm chart version 0.2.0 or later for deployment
• Suggested versions
  • Recommended infra-modules version 0.1.3 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.2.2 or later for deployment

Change Log

Added

• SDK: Serializer now supports Nullable versions of serializable enums.
• SDK: Database scan job system now support priorities for jobs, such that a high-priority job can cause a low-priority job to be paused. For example, notification campaign jobs have higher priority than scheduled player deletion jobs.
• SDK: Database scan jobs for triggering schema version migration for all players and guilds.
• SDK: Game client now detects and reports ongoing maintenance even if server has been shut down. The status is fetched from a hint file in CDN.
• SDK: Server support for validating Facebook Login social login claims.
• SDK: Broadcast messages can be targeted by player ID or player segmentation.
• SDK: IAdminApiDataCache service for controllers for cached data needs in admin API.
• SDK: Provide segment size estimates by periodic sampling from the database.
• SDK: New audit log event target types for broadcasts and notifications.
• SDK: New http entrypoint for bulk validating players by ID, used by message audience component in dashboard.
• SDK: NotificationCampaign options section for specifying throughput parameters of notification campaigns.
• SDK: Support added for API endpoints to be rooted under paths other than /api.
• Dashboard: Export Player admin action now has a download button and preview and copying is disabled on very large exports to prevent browser timeouts.
• Dashboard: Import Game Entities and Overwrite Player can now use a file as a source.
• Dashboard: Raw data component now has collapsible sections to hide large data blobs for better UX and performance on some browsers.
• Dashboard: New "Scan Jobs" page to view and manage jobs.
• Dashboard: New MetaListCard and MetaCollapse components that make it much easier to quickly build consistent looking UI elements with utilities like searching, filtering and sorting.
• Dashboard: New MessageAudienceForm component for targeting broadcasts (and eventually notifications).
• Dashboard: New LocalizedMessageContent component for providing text content to messages (mail, broadcast, notification).

Changed

• SDK: Remove obsolete InMemoryLogger.
• SDK: Elements of MetaSerializable Enums are checked to be unique. For example enum { A=1, B=1 } is no longer allowed.
• SDK: Player event log refactored to remove game-specific rendering code from the Dashboard.
• SDK: Include the binary-serialized client/server states (decoded into plaintext) in client log if a Desync happens. Helps debugging in cases where state diff is empty for some reason.
• SDK: Command line arguments are now Case Sensitive.
• SDK: New command line short-hands for specifying log level, eg, dotnet run -LogLevel=Information, for enabling metrics (-EnableMetrics=true), setting remoting port (-RemotingPort=6000), and for setting sharding config (-ShardingConfig="path/to/config.json").
• SDK: Forward slash syntax for command line arguments (foo.exe /Arg) is no longer supported, and is an error. Use -Short or --Section:LongForms instead.
• SDK: Dashless syntax for command line arguments (foo.exe Foo:Bar=1) is no longer supported, and is an error. Use -Short or --Section:LongForms instead.
• SDK: Specifying same argument in command line twice is now an error, regardless whether the value is the same or not. This applies to short-hands as well, i.e. .. -LogLevel=Information --Logging:Level=Information is an error.
• SDK: Specifying unrecognized command line arguments is now an error.
• SDK: MetaplaySDK.ScheduledMaintenanceMode is now exposed via MetaplaySDK.MaintenanceMode. To handle all situations in which this value is updated, a helper MetaplaySDK.MaintenanceModeChanged event has been added.
• SDK: Silence some unneeded Debug level logging to reduce overall volume.
• SDK: Remove explicit use of GeoTrust certificate: Apple has now update their certificates, so this hack is no longer needed.
• SDK: Don't log errors from server's connection code when packet parsing error is caused by well-known kinds of traffic (specifically, HTTP requests).
• SDK: If AdminApi (Dashboard), or any other service actor, fails to start during server startup sequence, the server is terminated immediately instead of waiting for a 5 minute timeout.
• SDK: Undo hack in segmentation info returned by SegmentationController.GetSegmentation() and provide per-segment info in a single list of segments.
• SDK: Add segment size estimates to segmentation info.
• SDK: Server now force terminates on with a single Ctrl-C. Previously server required two Ctrl-C signals.
• SDK: Upgrade to .NET 5.0.5 in Dockerfiles: fixes the NuGet certificate problem.
• SDK: Add DeploymentOptions.RequiredMetaplayVersion, so infra can indicate a minimum required version that it is compatible with. Replaces the old DeploymentOptions.SupportedRelease.
• Metrics: game_entity_ask_duration measures time of EntityAskAsync calls and it now includes the delay of the Entity getting rescheduled for execution (in addition to the message delivery and processing durations). This can increase observed durations very slightly.
• Metrics: Fixed metaplay_diagnostics_ping_timeouts_total rarely counting succesful pings as expired.
• Dashboard: Player and guild searching by name are now much faster, as the searches are now performed using a suffix table that can efficiently utilize an index.
• Dashboard: Most list elements have been refactored to use the new MetaListCard component and its utilities.
• Dashboard: Various fixes and updates to broadcasts UI, removed WIP disclaimer.
• Dashboard: Show Metaplay release in Runtime Options / Deployment.

Fixed

• SDK: Support deserialization of types with a non-public parameterless constructor also in Unity Editor.
• SDK: Understandable error messages for missing LogicInit.Initialize() or MetaSerialization.Initialize() when they are used.
• SDK: Fix SearchEntitiesByIdAsync() to use prefix search instead of substring search (improves performance significantly).
• SDK: Fix comparison methods of DynamicEnum<> to account for null arguments.
• SDK: Make serializer work also for private properties and fields of base classes.
• SDK: Fixed bots to be able to re-create their Player states in case they're lost from the database.
• SDK: Assign PlayerModel's and GuildModel's GameConfig, LogicVersion and Log properties in the actors right after loading the persisted model, so that they're available already in MigrateState.
• Dashboard: Fixed mobile headerbar overflow when sidebar is open.
• Dashboard: Card showing incidents from the last 24 hours no longer times out if there are too many incidents. The sample size is reduced automatically if card would sample too many incidents.
• Dashboard: Fixed page position not always starting from the top on most browsers.
• Dashboard: Fixed errors in the incident report client logs sometimes not being highlighted.
• Dashboard: Broadcast delete uses "edit" permission.