Highlights

• New feature: Leagues is now out of preview. The new leagues release now has full support for player leagues, where players face off against each other in local leaderboards and get rewards and rank-ups based on their performance. Check out the Quickstart Guide to get started.

• Major improvement: Upgrade to Vue 3 (compatibility mode) has been rolled out to the LiveOps Dashboard. Vue 3 brings native support for TypeScript, better performance, and a better developer experience for making your own dashboard components. This upgrade also enables you to leverage the growing ecosystem of open-source Vue 3 plugins and components. The upgrade is done in compatibility mode, which means that most Vue 2 code will continue to work. We will continue to upgrade our dashboard components and dependencies to Vue 3 in the coming releases and eventually retire the compatibility mode.

• Major improvement: Serialization performance has been improved by up to 3-4x and memory allocations have been significantly reduced. The serializer generation is also significantly faster within Unity.

Breaking Changes

• This release requires a synchronized upgrade of the client and the server due to backward-incompatible changes in the networking protocol.
  • Action required: Easiest is to bump LogicVersion and update the game client and server synchronously._
• Major dashboard dependency updates with each their own braking changes: Vue 2 -> 3 (compatibility mode), Vue Router 3 -> 4, Vite 3 -> 4, Cypress 11 -> 12. This is a complex update but most of the changes are in the core SDK. We will work with the affected customers to migrate their code as needed.
  • Action Required: You may need to delete your node_modules folder and reinstall dependencies with npm ci. NPM can get confused with major updates like this.
  • Known Issue: The bootstrap-vue UI component library is not, and will likely never be, compatible with Vue 3 due to the developer community getting disrupted by Russia's invasion of Ukraine. We have implemented workarounds to keep it functional but the intent is to replace it with a Vue 3 compatible library in the future.

INFO

Note: If you have a service contract signed with Metaplay, all the breaking changes have been fixed already in the SDK upgrade pull request of your project. Otherwise, please see CHANGELOG.md for a full list of changes, along with the HelloWorld and Idler samples for references on how to apply the changes.

Notable LiveOps Dashboard Changes

• Added support for component entry points to various dashboard pages. You can add, remove or replace default components with custom components on the OverviewView, GameConfigListView, GameConfigDetailsView and GameConfigDiffView pages.
• Added ability to pause updates of MetaListCards. This is useful for example when looking at the global incident reports and you don't want the list refreshing while browsing it.
• Added a toggle to incident reports for enabling or disabling the rich text styling of the Unity client logs.
• The following components have been added as a part of migrating to Vue 3 and are now in use in the dashboard:
  • MetaInputSelect - A dropdown component that supports searching, async options loading, auto-completion, multiple selection, and more.
  • MetaInputPlayerSelect - A dropdown component for searching and selecting a player.
  • MetaInputGuildSelect - A dropdown component for searching and selecting a guild.
  • MetaInputDateTime - A date and time picker component.
  • MetaInputDateTimeRange - A date and time range (start + end time) picker component.
• You can now search for players directly in the "reconnect accounts" dialog instead of pasting in a player ID.
• Entity refresher and schema migrator jobs now report failed entities in more detail: entity ids, failure timestamps, and error messages.
• Creating a new notification campaign by duplicating an old one has been moved from the list page to the detail page. Also, various other minor changes to make the notification pages behave more consistently with the broadcast pages.

Notable Under-the-Hood Changes

• Significant improvements to serialization:
  • Performance of the serializer has been improved by 3-4x by using the modern Span<T> data types. Unity 2021 is required for Span<T> support and in older Unity versions, the spans are emulated at the cost of some performance. We recommend upgrading to Unity 2021 LTS if performance is of the essence.
  • The serializer performance improvements translate directly to the time consumed by the checksumming as most of the time of checksumming is spent in serializing the data.
  • The serializer code generation was made significantly faster by using Unity's own C# compiler via AssemblyBuilder. This avoids the cold-start performance hit present when using Roslyn directly.
  • The serializer memory allocations have been significantly reduced by recycleing a set of thread-local SegmentedIOBuffers which themselves recycle the individual memory pages via ArrayPool<T>.
• New experimental Docker-based integration tests in Scripts/integration-tests.py which are easier to use with various CI systems, including Github Actions and Bitbucket Pipelines. If you'd like to start using them, please talk to us.
• It is now possible to run local server load tests using BotClient without MySQL by giving the server the --Database:SqliteInMemory=true argument on the command line. The in-memory SQLite is performant enough to allow for thousands of bots locally.
• Metaplay now includes a set of Roslyn analyzers for features that don't work (or at all) with Unity WebGL builds. Setting METAPLAY_ENABLE_WEBGL will enable the warnings -- we recommend doing this on all platforms so the warning doesn't go unnoticed. See Metaplay & WebGL for more information.
• The built-in HTTP server support for multiple authentication domains has been improved to make it more robust and easier to extend with new authentication methods.
• Game config specialization (for A/B test variants) now causes significantly less pressure on the garbage collector, especially for the LOH (large object heap).
• The Offer Groups feature's CPU usage has been significantly improved, especially to avoid large spikes when lots of offers are in use.
• New Offer Groups feature: MaxOffersActive, see Getting Started with In-Game Offers for details.
• We are migrating our core dashboard project from Vue 2 to Vue 3. This change also involves migrating our core components from the Options API to the Composition API to ensure the readability and maintainability of our code. For more on this topic, check out the Composition API FAQComposition API FAQ. Note: The Options API is not deprecated and you can continue to use it to build your custom components.

Notable Documentation Changes

• A new guide added to the Wordle series: Tutorial: Cheat-Proof Gameplay is available in the Getting Started section.
• The Logs & Debugging page has been rewritten with complete and up-to-date information on all the possibilities for data logging Metaplay offers.
• Two guides for the new Leagues feature have been added: Quickstart Guide and Customizing Leagues.
• A new section called Custom Analytics Context has been added to Implementing Analytics Events in Game Logic

Version Compatibility

Infrastructure and Helm chart compatibilities for this release:

• Minimum version requirements
  • Requires infra-modules version 0.2.2 or later for infrastructure
  • Requires metaplay-gameserver Helm chart version 0.4.4 or later for deployment
• Suggested versions
  • Recommended infra-modules version 0.2.7 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.4.5 or later for deployment

Change Log

Breaking

• SDK: The MetaplayClient SDK default integration class is now abstract and integrations should declare a derived class for type-safe access to the current player model.

  • Action Required: Introduce a MetaplayClient class in the integration that inherits from MetaplayClientBase<TPlayerModel>, substituting your concrete PlayerModel class as the template parameter. Reusing the name MetaplayClient should make the impact on using code minimal. The implementation of the class can be empty, the static MetaplayClient API methods are preserved in the base class.

• SDK: ISharedGameConfig's library accessors have been restructured to require less boilerplate, using an IGameConfigLibrary<,> interface.

  • Action Required: If your project implements ISharedGameConfig directly instead of via SharedGameConfigTemplate or SharedGameConfigBase, update the library accessors to adhere to the new interface.

• SDK: The Unity localizations build is now expected to place a single-archive copy of localizations as GameConfig/Localizations.mpa.

  • Action Required: Update your GameConfigBuilder to build localizations into a single file and use the file when uploading the localizations to the server:

      const string ServerLocalizationsPath = "Backend/Server/GameConfig/Localizations.mpa";
  
      public static async Task TryBuildLocalizations()
      {
          // Build Localizations & write each language in its own file
          await BuildArchiveAsync(ServerLocalizationsPath,
              ArchiveStorageFormat.SingleFile,
              () => BuildLocalizationsArchiveAsync(MetaTime.Now),
              onSuccessHandler: fullArchive =>
              {
                  // Export Localizations into StreamingAssets/ in FolderEncoding format
                  Debug.Log($"Writing Localizations archive as multiple files into {ClientLocalizationsPath}");
                  ConfigArchive.FolderEncoding.WriteToDirectory(fullArchive, ClientLocalizationsPath);
              });
      }
  
      public static async Task PublishLocalizationsToLocal()
      {
          ConfigArchive localizationsArchive = await ConfigArchive.FromFileAsync(ServerLocalizationsPath);
          await GameConfigBuildUtil.PublishLocalizationArchiveToServerAsync("http://localhost:5550/api/", localizationsArchive, authorizationToken: null, confirmDialog: false);
      }

• SDK: As the localizations archive is now longer sourced from within the Unity assets folder the server docker build no longer includes the Assets/StreamingAssets/ directory.

  • Action Required: Make sure that you don't rely on any other data being copied to the server build from the directory! Or if you do, modify Dockerfile.server to copy them explicitly.

• SDK: GameConfigBuildUtil.PublishArchiveToServerAsync() has been replaced with PublishGameConfigArchiveToServerAsync() and PublishLocalizationArchiveToServerAsync().

  • Action Required: Replace any usage of the old method with the new ones, depending on which type of archive is being published.

• SDK: SocialAuthenticationClaimGooglePlay is now SocialAuthenticationClaimGooglePlayV1 to clearly communicate it is the legacy version.

  • Action Required: Rename any usage of the old type with the new.

• SDK: playerModel.HasMetaOffersToRefresh() has been replaced with playerModel.GetMetaOfferGroupsRefreshInfo() which returns a list of refreshable offer groups. This is used to reduce workload on the server by reducing the number of offer groups it needs to consider when refreshing.

  • Action Required: Instead of calling HasMetaOffersToRefresh(), you should now use GetMetaOfferGroupsRefreshInfo() and call the HasAny() method on the result, and also pass the result to the PlayerRefreshMetaOffers action.

• SDK: To enable WebGL support in the client, it is now required to define the preprocessing symbol METAPLAY_ENABLE_WEBGL. This also enables warnings about features which are poorly-supported in Unity WebGL builds. See the documentation page Metaplay & WebGL for details.

  • Action Required: If you make WebGL builds of your project, add a file called csc.rsp in your Assets folder, with a line saying -define:METAPLAY_ENABLE_WEBGL.

• SDK: DatabaseScanJobSpec's API has been changed: added method ComputeAggregateStatistics which combines multiple workers' statistics into one, and changed method CreateSummary to take only one statistics object instead of multiple.

  • Action Required: If you define custom database scan jobs, update their DatabaseScanJobSpecs to adhere to the new API. Note that you likely already have the necessary code for ComputeAggregateStatistics in your existing CreateSummary method, so this is likely a matter or minor refactoring.

• Dashboard: Major dependency updates with each their own braking changes: Vue 2 -> 3 (compatibility mode), Vue Router 3 -> 4, Vite 3 -> 4, Cypress 11 -> 12. This is a complex update but most of the changes are in the core SDK. We will work with the affected customers to migrate their code as needed.

  • Action Required: You may need to delete your node_modules folder and reinstall dependencies with npm ci. NPM can get confused with major updates like this.

• Dashboard: Vue 3 compatibility mode has been enabled. This means that Vue 2 and Vue 3 APIs can be used interchangeably, but there are some breaking changes and warnings about deprecated APIs.

  • Action Required: Update your custom dashboard components to use the new Vue 3 APIs where possible. See the Vue 3 migration guide for more information.

• Dashboard: Vue 3 has a new component registration API that is incompatible with Vue 2.

  • Action Required: Update your custom dashboard components to use app.component() instead of Vue.component().

• Dashboard: Vue 3 has a new v-model syntax that is incompatible with Vue 2. The current compatibility mode allows both syntaxes to be used, but this will be removed in a future release.

  • Action Required: Form inputs using the v-model property and an input event like @input or @update at the same time may have a race condition where the input event is fired before the v-model is updated. Update your custom dashboard components to use the input event's value instead of the v-model value to guarantee the updated value is used.

• Dashboard: Vue 3 has changed the execution order of v-for and v-if directives. The official recommendation is to not use v-if and v-for on the same element as the order is ambiguous to the reader.

  • Action Required: Update your custom dashboard components to not use v-if and v-for on the same element and instead use v-if on a child element to make the order explicit.

• Dashboard: Vue Router v4 now has built-in support for accessing the current route and router instances via the useRoute() and useRouter() composition APIs. Our previous workaround for this has been removed.

  • Action Required: Migrate all imports of useRoute() and useRouter() to import from vue-router.

• Dashboard: Vue Router v4 has changed the route props API. Props can now be string[] in addition to string.

  • Action Required: Wrap all route props with the new routeParamToSingleValue() utility function from the core dashboard module to continue with the old behavior.

• Dashboard: Vue Router v4 has changed how routes are added to the router. The addNavigationEntry() integration API has been updated to work with the new router by moving the content of route.meta parameter into it's own top-level parameter in the addNavigationEntry() function.

  • Action Required: Update all calls to addNavigationEntry() to use the new, separate route metadata parameter.

• Dashboard: The displayName field of GameSpecificReward was removed because it was obsolete.

  • Action Required: Update any calls to addPlayerRewards() to remove the displayName field.

• Dashboard: Cypress 12 has enabled isolated testing by default. This means that each it() command runs in a separate, clean browser session. This is a breaking change for tests that rely on the old behavior.

  • Action Required: Update you existing tests to use the old behavior by adding { testIsolation: false } to incompatible tests or update the tests to run in one it() command instead of multiple, as needed.

• Dashboard: Meta-Teleport component has been removed in favour of a new type-safe API to dynamically update the headerbar title.

  • Action Required: Use the new useHeaderbar() composition API of the core dashboard module to update the title.

• Dashboard: The unit tests are now run explicitly by the Dockerfile.

  • Action Required: Remove the npm run test:unit from your Backend/Dashboard/package.json from the build command.

Added

• SDK: Added virtual PlayerSegmentInfoBase.MatchesPlayer for the ability to customize the player segment matching logic in the integration.
• SDK: Support in-memory SQLite databases with the --Database:SqliteInMemory=true option. Useful for benchmarking locally with BotClient.
• SDK: Added MetaOfferGroupInfoBase.MaxOffersActive that can be used to limit the number of simultaneously active offers in an offer group.
• SDK: Erroneous activable states in player model (states that no longer have an associated config item) are now automatically purged by the server after a configurable delay from the latest game config publish.
• SDK: New AuthenticationConflictAutoResolver integration allows customizing social login conflict auto-resolution rules.
• SDK: Added ranks support to leagues. The league manager can now handle promotions and demotions between seasons.
• SDK: MetaTask.Run() allows executing tasks on a chosen Scheduler without the pitfalls of Task.Factory.StartNew() (no need to call Unwrap()).
• SDK: MetaTask.UnityMainScheduler is a convenience getter of the Unity Main thread scheduler. With above MetaTask.Run(), posting work on the correct thread is easy.
• SDK: MetaTask.BackgroundScheduler is a convenience getter of the best available background scheduler. On WebGL this is the main thread.
• SDK: Task.GetCompletedResult() is a convenience helper for Task.Result which throws (instead of blocking) if Result is not yet available. Convenient for avoiding accidental deadlocks especially on WebGL.
• SDK: Player incident reports now produce PlayerEventIncidentRecorded analytics events.
• SDK: Added a client code analyzer for WebGL projects, warning about usage of features which are known to be poorly supported in Unity's WebGL builds.
• SDK: UDP Passthrough allows hosting custom UDP servers on embedded within the game server.
• SDK: New docker-based integration tests in Scripts/integration-tests.py. The old Scripts/tests.py is now deprecated and will be removed in the future.
• SDK: Support specifying custom userland Backend/ directory to Dockerfile.server via --build-arg BACKEND_DIR=xyz to avoid needing to modify the Dockerfile itself when using a custom directory.
• SDK: Add ARM64 platform support to server project files.
• Dashboard: Added ability to pause updates of MetaListCards.
• Dashboard: Added pausing to Incident Reports so that they can be examined more easily.
• Dashboard: Added a toggle to Incident Reports for enabling or disabling the rich text styling of the Unity client logs.
• Dashboard: Added ability to pass props directly into components that are created by UiPlacements.
• Dashboard: Added new component entry points to the OverviewView, GameConfigListView, GameConfigDetailsView and GameConfigDiffView pages. You can now add or remove injected components to these views.
• Dashboard: Improved leagues support and added the ability to see the promotion and demotion statistics for historical seasons.
• Dashboard: The following components have been added as a part of migrating to Vue 3:
  • MetaInputSelect - A dropdown component that supports searching, async options loading, auto-completion, multiple selection, and more.
  • MetaInputPlayerSelect - A dropdown component for searching and selecting a player.
  • MetaInputGuildSelect - A dropdown component for searching and selecting a guild.
  • MetaInputDateTime - A date and time picker component.
  • MetaInputDateTimeRange - A date and time range (start + end time) picker component.
• Dashboard: Entity refresher and schema migrator jobs now report failed entities in more detail: entity ids, failure timestamps, and error messages.

Changed

• Sample projects: The Sample-Server.sln files have been moved to the project Backend/ directory in all sample projects.
• Sample projects: The contents of Assets/SharedCode is now built into a separate SharedCode assembly that does not reference the default assemblies or UnityEngine assemblies.
• Sample projects: Upgrade to Unity 2019.3.19f1.
• SDK: Separated mutable state from MetaplayClient into MetaplayClientState accessed via the static accessors in MetaplayClient.
• SDK: Removed EmptyGameLogic.cs previously used for providing minimal integration for client project to build.
• SDK: Use Unity's AssemblyBuilder to compile the generated serializer code. On some machines was measured to be about 4x faster.
• SDK: Directory Temp/Metaplay/ is now used for Unity temporary files instead of MetaplayTemp/ to avoid clutter in the project root.
• SDK: Prevent generation of runtime serializable type information into the Unity editor version of Metaplay.Generated.dll for improved performance.
• SDK: Remove curl from the Docker images due to frequent vulnerabilities in the package. Also remove the curl static.gc.apple.com test in Dockerfile as it's covered by the unit tests.
• SDK: The runtime option AdminApi:Type = AuthenticationType.Auth0 is deprecated and will be removed in a future release. Use the more general AuthenticationType.JWT instead.
• SDK: Optimized the allocations associated with config specialization in server by introducing ReadOnlyConfigArchive.
• SDK: Improve the serialization buffer handling by re-using the memory of individual SegmentedIOBuffer segments and then using recycled buffers in the MetaSerialization APIs directly. This considerably reduces the number of memory allocations done by the serializers and reduces the amount of memory retained by the various server-side actors.
• SDK: Complete rewrite of the IOWriter class for improved performance.
• SDK: Optimized generated serializer code by using modern C# Span<T> APIs.
• SDK: Allow supplying GoogleSheet credentials (option GoogleSheets.CredentialsPath) as AWS secrets manager URL in addition to local file.
• SDK: Checksum mismatches now produce significantly shorter messages. Full state dumps are no longer done.
• SDK: PlayerActor.OnClientSessionHandshake() is deprecated in favor of OnClientSessionHandshakeAsync().
• SDK: PlayerActor.OnSessionStart() is deprecated in favor of OnSessionStartAsync().
• SDK: EntityActor.CastMessage(), EntityAskAsync(), and other messaging functions are now thread-safe also within a single actor and may be used from background threads.
• SDK: LogicVersionMismatch errors are no longer reported as player incidents. Logic version mismatches are often expected, especially after a server update.
• SDK: Remove RecyclingSerializer and replace all usage with calls to MetaSerialization as it now uses recycled buffers internally.
• SDK: Increase DB access timeouts to tolerate load spikes better. This improves behavior when a large number of players disconnect at the same time, such as in the case of enabling maintenance mode.
• SDK: Device identity is now tracked separately from per-device authentication. On client side device identity is represented as MetaplaySDK.DeviceGuid which is negotiated at session startup and doesn't depend on the DeviceId authentication method. The legacy per-device book keeping in PlayerModel has been repurposed as DeviceHistory and additional statistics are tracked per device on login. Existing device identification based on DeviceId authentication is migrated to the new scheme and partial stats are migrated from recent login history.
• SDK: Updated the client-side IAPManager to support Unity Purchasing 4.6.0 (regarding changes to IStoreListener.OnInitializeFailed() and IAppleExtensions.RestoreTransactions()).
• SDK: Added preservation for more assemblies in link.xml: Metaplay.Unity and the game-specific shared code assembly. This should avoid issues caused by Unity's code stripping, and reduce the need for explicit [Preserve] attributes in code.
• SDK: Some non-mutating struct methods have been changed to be readonly to improve performance.
• SDK: Dockerfile.server now builds the C# game server before building the dashboard. Dashboard build uses Debian (bullseye-slim) -based base image.
• SDK: Dockerfile.server now includes BotClient in the built image. In a future release, the BotClient docker images will be replaced with the server image, the ECR repository and Dockerfile.botclient deprecated and removed.
• SDK: Dockerfile.server now generates the serializer code by starting the server after the build.
• Dashboard: The CoreUiPlacement component now forwards all props and listeners to child components. Additionally removed small wrapper components that were used to forward props when using UiPlacements for example for the PlayerAuditLogCard.
• Dashboard: Migrated multiple components from the Options API SFC based syntax to the Composition API Setup based syntax.
• Dashboard: Creating a new notification campaign by duplicating an old one has been moved from the list page to the detail page. Also various other minor changes to make the notification pages behave more consistently with the broadcast pages.

Fixed

• SDK: Fix the process to properly exit after adding an EFCore database migration by delaying the registration of the SIGTERM handler.
• SDK: Fixed OpenId issuer verification used with Facebook limited login.
• SDK: POST, PATCH, and DELETE http request to unknown AdminApi paths are now logged, just like GETs were.
• SDK: Incorrectly declared AdminApi controller methods are now detected early in server startup.
• SDK: Fix IAPManager's behavior when using Unity's development-mode fake IAP store, which would erroneously cause purchases to be displayed as duplicates in the dashboard.
• SDK: Fix rare race condition in client MetaplayConnection tear down by handling cancel request before any other operations.
• SDK: Fix large integer values being incorrectly rounded on the dashboard database entity inspector.
• SDK: Network diagnostics now use URLs to existing files to avoid generating 404s on CDN.
• SDK: Player incident reports caused by PlayerChecksumMismatchConnectionError are now grouped more appropriately in "top incidents" views. This is done by omitting noisy details from the incident's "fingerprint".
• SDK: AdminApi entity search no longer throws an internal server error when an empty search string is used and the total entity count is very low.
• SDK: AdminApi: When JSON-parsing MetaTime from a string with a numeric time offset specifier, the offset is now correctly applied, instead of erroneously applying also the server's local time offset.
• SDK: AdminApi: Endpoints that configure audience targeting now disallow null Ids.
• SDK: Game Config cache directory cleaning now works on WebGL builds.
• SDK: The Model Inspector tool in the Unity editor now automatically switches to an up-to-date Model reference in case the old reference goes stale. For example, when a new session starts, the inspector will now switch to the new PlayerModel.
• SDK: Google Play Refunds now make the request using the order id (as expected by Google's API), instead of erroneously using the transaction id.
• Dashboard: Fixed usability issue when displaying extra long text on the MessageAudienceForm, SegmentsCard and TargetingCard.
• Dashboard: The player incident report view now parses and applies the client logs' styling elements explicitly. Previously it parsed them as HTML, which produced incorrect results because Unity's "rich text" styling is not actually HTML.
• Dashboard: Fixed displaying of the TargetingCard.vue when a new game config where a target segment has been removed is published.