Metaplay Docs

Appearance

Release 12

June 4th, 2021

Highlights ​

Viewing an offer shows a visual overview of how it has been configured!

  • New feature: Analytics Events expands the existing Player Event Log to support writing the events out to external storage and data streams for better integration with 3rd party analytics pipelines. Writing events to S3 as JSON is supported out-of-the-box and custom data sinks to support any formats or storages can be added. The feature is also generalized to support Guilds. See Implementing Analytics Events in Game Logic and Streaming Analytics Events to External Storage for more information.

All registered Analytics Events are viewable in the dashboard.

  • New feature: Social authentication via "Facebook Limited Login" tokens. This may help with iOS App Tracking Transparency requirements.
  • New feature: Push notification campaigns can now be targeted using player segments.

Composing a notification for "high rollers"

  • New feature: Localization support. Metaplay makes it easier to localize your game by managing the localization files, including the support for OTA updates. See Localization.
  • New feature: "AWS Backup" based backups of databases are now supported to offer more robust and easier storage of RDS snapshots for extended periods of time. Further documentation is available at: Database Infrastructure Operations
  • New feature: Guild Invite Codes allows players to create invite codes to share with their friends, with optional usage and time limits. See Implementing Guild Invitesfor more information.

This guild has one active invite code right now!

  • New feature: Broadcast message contents are now customizable to support game-specific mail formats.
  • New feature: New dashboard visualisation for segments. Integration of player segmentation has also been simplified and documented in Implementing Player Segments.

You can easily see how segments are being used in your game!

Breaking Changes & Migrations ​

  • This release intentionally breaks client/server backward compatibility. The game must perform a fully synchronized update of the client and the server when switching to R12.
    • Bump the****** SupportedLogicVersions ********when releasing the first game update that includes R12.**
  • The EntityActor message handling methods are now marked with various attributes instead of using magic names to identify the handlers. This makes the usage more explicit (and less prone to errors) as well as improves debuggability as the different handlers are now easy to identify in any stack traces, based on the method names alone. The old special method names are not allowed to avoid accidentally relying on them (the methods would not do anything anymore).
    • The following attributes have been introduced:
      • [CommandHandler] replaces the old HandleCommand()
      • [MessageHandler] replaces the old HandleMessage()
      • [EntityAskHandler] replaces the old HandleEntityAsk()
      • [EntitySynchronizeHandler] replaces the old HandleEntitySynchronize()
      • [PubSubMessageHandler] replaces the old HandlePubSubMessage()
    • No action needed. All existing code has been migrated to use the new attributes!
  • The game-facing interface of the new server-side analytics events is unified with the player event log. To accommodate this, the following changes were made to how events are defined and logged:
    • The event base class is now called PlayerEventBase instead of PlayerEventLogEntryPayload, and the event types need to have the [AnalyticsEvent(...)] attribute.
    • To allow visualization of event types in the dashboard, an event's title is no longer a property of the event instance, but rather of the event type itself. Thus, the virtual EventTitle property has been removed. By default, the name of the event class is used to determine the title, but to use a custom title, the displayName parameter can be given to the AnalyticsEvent.
    • Events are now logged using playerModel.EventStream.Event(...) instead of playerModel.ServerListener.OnLoggableEvent(...).
    • No action needed. All existing code has been migrated to use the new kind of event definition and logging.
  • New [MetaImplicitMembersRange] and [MetaImplicitMembersDefaultRangeForMostDerivedClass] attributes are required on ImplicitMembers-flagged serializable base classes. See the section [MetaSerializable] Attribute in Deep Dive: Data Serialization for more information.
    • No action needed. The attributes have been added to all existing base classes with ImplicitMembers.
  • Pager configurations in infra-modules have been changed and for PagerDuty and Opsgenie integrations, the only supported configuration keys in the pager_targets map are now pagerduty_alertmanager_key, pagerduty_cloudwatch_key, opsgenie_alertmanager_key, and opsgenie_cloudwatch_key. All other PagerDuty and Opsgenie keys in configurations have been deprecated.
    • As the key names imply, _alertmanager_ keys are used to configure Prometheus AlertManager and the _cloudwatch_ keys are used for AWS CloudWatch Alarm configurations. These are separated as the paging system side configurations are often different (e.g. PagerDuty requires the integration to be specifically of type CloudWatch for CloudWatch integrations, whereas Prometheus AlertManager integrates through a more generic integration point).
    • Talk to us when configuring these integrations!
  • The database has been refactored to better separate SDK and game-specific code. All game-specific query code should now go into the GameDatabase class, and all Metaplay query code is in MetaDatabase class. The SDK database queries can now be performed with MetaDatabase.Get().SomeQueryAsync() and game-specific queries with GameDatabase.Get().SomeCustomQuery().
    • No action needed. All code has been migrated to use the new database API.

Under-the-Hood Highlights ​

  • The server-side CloudCore and Game.Server project sources have been split to Metaplay/ for Metaplay SDK source files and Game/ for any game-specific source files, improving the core vs userland separation.
  • Dashboard views and components are now auto-loaded from the source tree and globally imported as lazy-loaded modules, there's no longer a need to explicitly import components and introduce them to Vue.
  • Improved Dashboard customization. Dashboard components can now be overridden by introducing an override component in the game_specific folder by the same component file name. Integration hooks for existing components provided through the new integration api. Customization documentation here: Customizing the LiveOps Dashboard Frontend
  • Facebook Deauthorize Callback URL is now supported. By configuring this callback in the Facebook App, users logging out from the game app on Facebook (i.e. not within the game) will be logged out of the Facebook Social Account in game as well.
  • The database access now supports query priorities. You can specify the priority with MetaDatabase.Get(QueryPriority.Xyz). For any expensive or long-running queries, QueryPriority.Low should be used.
  • Loki-based logging has been refactored and will now by default separate log ingestion and query paths and allow more granular control over ingestion and reader pod counts to alleviate issues in congested environments. Further documentation is available at Logging
  • fluent-bit can now be configured to output logs to S3 and CloudWatch Logs destinations. The Logging page in the documentation provides detailed instructions on how to enable these options.
  • MainGameConfigBuilder class has been introduced, which takes care of building and creating a binary archive of MainGameConfig. This clarifies the separation of the offline build step and the runtime loading (from binary archive). The class and the related GameConfigBuilderServices class are both userland classes and can be modified according to the game's needs.
  • In the Idler reference project, the Game Config build and publish operations are now triggered from Unity menus (instead of the GameConfigBuilder MonoBehaviour / prefab). This significantly simplifies the implementation and usage of the feature.
  • GoogleSheetFetcher now uses more efficient batch fetching of multiple sheets in a single operation. Use batch fetching in the example project. The fetcher (including the related DLLs) now lives under Editor/, so it doesn't get included in the builds.
  • The IOnDeserialized interface has been replaced by a [MetaOnDeserialized] attribute that can be used on methods of a serializable type. The new attribute works also on nested objects, unlike IOnDeserialized which was only called for the top-level deserialized object.
  • A [MetaOnMemberDeserializationFailure] attribute allows handling deserialization failures of individual members. This enables player and guild event logs to tolerate the removal or a backwards-incompatible change of an event type while still leaving the player or guild entity otherwise usable.
  • The Random Players and Random Guilds lists that were shown on the Players and Guilds Dashboard pages are now hidden behind the "Developer Mode" toggle - they were not particularly useful or interesting to non-developers.
  • The serializer generator now gives its internal methods unique names, thus avoiding overloads and decreasing the compilation time of the serializer.
  • The StringId interning code has been optimized to not allocate any memory for already-interned values: previously unnecessary memory allocations happened during the interning.
  • A GameOnSessionStarted method has been added to PlayerModel. This method is invoked when a player logs in and starts a session, as opposed to the existing GameOnRestoredFromPersistedState method (previously called GameOnStateRestored) which is called whenever the PlayerActor is woken up for any reason (including due to access from the LiveOps Dashboard).
  • Guild Framework can be accessed from Unity Editor. Select the MetaplaySDK GameObject in the Editor to observe the Guild state in the Inspector.

A custom Unity editor to quickly prototype and interact with guilds.

  • Many usability and visual improvements have been made across the Dashboard. For example:

    • Broadcasts and Push Notifications dashboard pages have been re-worked to make them more consistent and easier to use.

      An overview of how a broadcast has been configured. Received by 43 players already!

    • More tooltips on various times and durations all over the LiveOps Dashboard to avoid doing mental math!

      Hovering over a date with dashed underlines reveals more!

    • Player's login history now includes their locations if you have IP Geolocation enabled.

      Identifying flags is hard, isn't it? Luckily you can mouse over them to see the country name - no need to dig out your atlas!)

    • Broadcast Log on the Dashboard's Player Details page shows which broadcasts a player has or has not received.

      This player has received one broadcast.

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

Change Log ​

Added ​

  • SDK: Serializer now supports the 'char' and 'char?' types (serialized as unsigned 16-bit integer).
  • SDK: Augmented player segmentation utilities to support segmenting based on more than just integer-typed player properties.
  • SDK: Added methods of SIP (Session Initiation Protocol) as well-known prefixes to server's detection of well-known traffic.
  • SDK: Added a health check request/response to the client protocol to be used by monitoring services.
  • SDK: Added more debugging diagnostics to login messages to help investigate connectivity issues.
  • SDK: Added MetaDuration.ToSimplifiedString, which excludes some of the least significant units.
  • SDK: Added PlayerModel.GameOnSessionStarted method, for custom model code to run specifically when player logs in and starts a session.
  • SDK: Added support for targeting notification campaigns based on player ID list and/or player segment, similarly to broadcasts.
  • SDK: Facebook Login validation now support OpenID Connect tokens. This allows use of Facebook Limited Login.
  • SDK: Added support for Facebook Deauthorization Callback url. If enabled, Facebook users deauthorizing the app on Facebook will get their Facebook account deassociated with their game account.
  • SDK: Preliminary support for collecting analytics events from the server (including shared logic) for the purposes of pushing it to an external storage.
  • SDK: Extended event logs to support guilds, and implemented basic SDK-side events.
  • SDK: Moved event logs' event and segment retention count configuration to server-side RuntimeOptions. Previously they were in virtual properties of the event log class. This also removes the need for a game-defined subclass of PlayerEventLogBase.
  • SDK: Various improvements to the utilities for activables, to further aid in defining game-specific events.
  • SDK: Made the SDK more aware of game-specific activables. Declaring game-specific kinds of activables with simple metadata attributes enables the SDK to visualize them automatically in the dashboard, without requiring game-specific modifications to the SDK code.
  • SDK: Added [MetaOnMemberDeserializationFailure] attribute for member-level deserialization failure handling.
  • SDK: Added MetaplaySDK.RunOnUnityThreadAsync for deferring Func<>s to Unity thread.
  • SDK: Added MetaplaySDK.LocalizationManager to manage OTA updates to localization files.
  • SDK: Added support for Guild Invite Codes to the guilds framework.
  • SDK: Added Guild information to the Unity Inspector of the MetaplaySDKBehavior component. Select the MetaplaySDK in the running editor to observe guild state.
  • Reference project: Added two example event features, implemented as activables: "Happy Hour" and "Special Producer Event".
  • Reference project: Extended the existing "Shop Offer" feature to leverage the extended SDK-side support for activables.
  • Dashboard: Added underlines to dates and durations that have a tooltip to make them more obvious.
  • Dashboard: New meta-time component that replaces the previous time-ago and duration components.
  • Dashboard: Added count of how many players have received each broadcast message.
  • Dashboard: Added list of broadcasts to player details page.
  • Dashboard: New dashboard component system that supports lazy loading and convenient game-specific overrides.
  • Dashboard: New game-specific integration interface in game_specific/integration.js, existing game-specific elements moved into the integration layer.
  • Dashboard: Added location to latest login list on player details page.
  • Dashboard: Useful out-of-the-box visualization of game-specific activables (such as events and offers). Both the general configuration and scheduling of activables can be viewed, as well as per-player state of each activable.

Changed ​

  • SDK: Moved all CloudCore and Game.Server sources to either Metaplay/ or Game/ folders, for Metaplay core sources and game-specific sources, respectively.
  • SDK: Update server dependencies: Akka.NET v1.4.18, AWSSDK v3.7, FirebaseAdmin v2.1.0, JSON.NET v13.0.1, JWT v8.2.0, YamlDotNet v11.1.1, Parquet.Net v3.8.6, Google.Apis v1.15.0.
  • SDK: Upgrade & pin .NET Core SDK image to 5.0.300 and runtime image to 5.0.6 to avoid accidental version drift.
  • SDK: ConfigParser.RegisterParseFunc is now private. Config library reference id parsers are registered automatically. Custom config parsers must be now be registered in CustomConfigParsers.RegisterCustomParsers (called from LogicInit) with ConfigParser.RegisterCustomParseFunc.
  • SDK: Serializer generator now avoids producing overloads of serializer-internal methods, decreasing the compilation time of the generated serializer.
  • SDK: Refactored the database: improve core-userland separation, support priority levels for database operations with throttling for low-priority queries, separate schema migration and re-sharding code into its own class.
  • SDK: Removed the Global singleton registry class, along with all usage of it.
  • SDK: Use BatchGet in GoogleSheetFetcher to significantly speed up the fetching. Suffix methods with Async and add CancellationTokens to methods.
  • SDK: The GoogleSheetFetcher is now only compiled for Editor builds.
  • SDK: MetaRecurringCalendarSchedule now uses a MetaCalendarPeriod-based recurrence (such as 5d) instead of a fixed set of supported recurrences (such as Monthly). Only one non-zero unit is supported in the recurrence.
  • SDK: InitialPlayerState no longer depends on game specific PlayerModel class.
  • SDK: New attributes to mark EntityActor methods for handling incoming commands/messages: [CommandHandler], [MessageHandler], [EntityAskHandler], [EntitySynchronizeHandler], [PubSubMessageHandler]. These replace the old magic-named methods HandleCommand(), HandleMessage(), etc. The magic-named methods are no longer allowed (to avoid accidentally relying on it).
  • SDK: Optimize memory allocations from StringId interning when value already exists.
  • SDK: Replace the GetAll method in GameConfigLibrary<TKey, TInfo> (for IGameConfigLibrary) with an EnumerateAll method that doesn't construct a new collection, and a GetInfoByKey method for getting a single item.
  • SDK: Added PlayerModelBase.PlayerId to make it predictably available.
  • SDK: Replace the IOnDeserialized interface with a [MetaOnDeserialized] attribute for methods, which supports on-deserialization hooks also for nested objects instead of only the top-level deserialized object.
  • SDK: MetaMembers of an object are now serialized in ascending tag id order, allowing to retain serialization checksum compatibility while changing member declaration order or moving members between a base class and a derived class.
  • SDK: Renamed PlayerModel.GameOnStateRestored to GameOnRestoredFromPersistedState and updated comments to clarify that it's called whenever actor is woken up, not just at player login.
  • SDK: Renamed PlayerModel.SessionStartTime to TimeAtFirstTick, since it's not the start time of the actual game session (if any).
  • SDK: Changed BroadcastMessageParams to refer to abstract BroadcastMessageContents to support game-specific broadcast message contents. The old implementation that creates MetaInGameGenericPlayerMail mail elements is re-introduced as GenericBroadcastMessageContents and GlobalState migration code has been added to migrate old broadcast messages.
  • SDK: Move broadcast target evaluation to work with more generic IPlayerFilter, so that logic can be shared with notifications.
  • SDK: The PlayerEventLog feature is now generalized to multiple entities (ie, Guilds) and renamed to Analytics Events.
  • SDK: When using MetaSerializableFlags.ImplicitMembers, a [MetaImplicitMembersRange(start, end)] is now required on base classes with data members. It is optional on the ultimate concrete class, but if omitted, [MetaImplicitMembersDefaultRangeForMostDerivedClass(start, end)] must be present on a base class or interface. The purpose of these range allocations is to allow adding members to base classes without changing the implicitly-tagged members on derived classes.
  • SDK: The deserializer now checks that the correct WireDataType is encoded also for builtin types (such as WireDataType.VarInt for int, and WireDataType.String string). Previously, the WireDataType for basic types was not checked, and invalid input would cause the deserializer to attempt to parse garbage.
  • SDK: Player deserialization no longer fails when a single event log entry payload fails to deserialize. The erroneous payload is instead replaced by a placeholder indicating the failure.
  • SDK: PrettyPrint now hides properties that are explicitly implemented from interface, matching default C# behavior.
  • SDK: PrettyPrint now hides properties that have [IgnoreDataMember] in any step of the ancestor chain.
  • SDK: PrettyPrint and JSON serializer now support all types of [Sensitive] fields, not just strings.
  • SDK: Admin API now requires that POST/PUT requests set their content-type headers to application/json.
  • Reference project: Upgrade to Unity 2019.4.24f1 (LTS).
  • Reference project: Use batch-fetching of Google Sheets when building MainGameConfig.
  • Reference project: MainGameConfig and Localizations are now built from Unity menu (Idler/Build xyz).
  • Reference project: MainGameConfig and Localizations publishing to server is also now triggered from Unity menu (Idler/Publish xyz).
  • Reference project: MainGameConfigBuilder is now its own class, to more clearly separate the runtime and build-time separation.
  • Reference project: Cleanup PlayerModel. Remove PlayerAvatar: move player profile info into PlayerModel and resources into PlayerWalletModel.
  • Dashboard: Guild members list is now a meta-list-card with search and sorting utilities.
  • Dashboard: Top incidents card is now a meta-list-card with filtering, search and sorting utilities.
  • Dashboard: Overview entry removed from sidebar in favour of a header logo link.
  • Dashboard: Added ability to launch player deletion job from scan jobs page.
  • Dashboard: Support src/game integration folders in place of src/game_specific.
  • Dashboard: Routes and sidebar navigation now configured together in navigation.js.
  • Dashboard: Random Players and Guilds list are now hidden unless user is in development mode.
  • Dashboard: In-game mail and broadcast content display and editing split into separate components to allow overriding.
  • Dashboard: Improvements to how segments are shown in the Dashboard, including overhaul of the segment detail page and consistent segment lists in other pages, such as the player details page.

Fixed ​

  • Dashboard: Removed duplicate created date labels from the player overview card. Oops!
  • Dashboard: Added missing permission tooltips to audit log and incident log related links.
  • SDK: Audit log events for player mails now include the correct mail ID.
  • SDK: Fixed bug in ClusterConfig.GetNodeShardIds() which caused some node loss to not properly trigger Entity subscription loss events with some cluster topologies.
  • SDK: Fixed precision issues in MetaTime.FromDateTime and MetaTime.ToDateTime for large dates by using integers instead of doubles.
  • SDK: Support Nullables generally in JsonConvert, instead of hard-coding support for Nullable<MetaTime>.
  • SDK: Serializing MetaTimes to JSON now includes sub-second resolution (previously was rounded to seconds).