Highlights

• Major improvement: LiveOps Dashboard subscriptions have been re-written in Vue 3's low-level reactive primitives for greatly increased performance and reduced browser memory usage. We have seen up to 100x improvements on live games with very large player models and a lot of components accessing the data simultaneously. The subscriptions documentation has been updated to cover the new API and more advanced use-cases: Working with Subscriptions.
• Major improvement: LiveOps Dashboard project tooling has been migrated to use PNPM instead of NPM and our SDK internals have been re-organized to benefit from this. PNPM can de-duplicate dependencies and dramatically increase the speeds of repeated install commands. Especially CI builds will see more than 10x speedups if they have been configured to share the PNPM cache between runs.
• Major improvement: Leagues system has been overhauled to support custom join flow and season scheduling, and a bunch of LiveOps Dasbhoard improvements. We've also improved the performance of leagues and divisions for games with large player bases.

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.
• The LiveOps Dashboard now uses PNPM to manage the project's dependencies and the project scripts have been updated to align with the common naming conventions in the ecosystem.
  • Action required: Use npm i -g pnpm to install PNPM and run pnpm i to re-initialize your dashboard project. Use pnpm dev to launch the local development server.
• The LiveOps Dashboard subscription API has changed for more consistency and easy of use. The built-in subscription options have also been migrated from the subscription module to the core module.
  • Action required: In the future, use the new subsciption API in your custom components. See Fetching Data from the Game Server for an updated guide on the new API.
• The game server and botclient Docker images have been unified. The game server Dockerfile will now also build the botclients in as part of the image.
  • Action required: When deploying botclients, be sure to use the game server ECR repo. Additionally when using the metaplay-loadtest Helm chart, please use version 0.3.0. This version has the correct entrypoints and paths to run the unified game server/botclient image.

INFO

Note: If you have a service contract signed with Metaplay, the breaking changes outside the list above 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 Under-the-Hood Changes

• Upgrade all SDK projects and samples to .NET 7. It brings many optimizations and C# version 11.0.
• Minimum required Unity version is now 2020.3.
• The NotificationForm component has been removed and replaced by the new NotificationFormButton component that takes advantage of our custom MetaActionModalButton modals. The new modal includes a loading indicator and error messages from the resulting API request.
• Logging simplification and optimizations:
  • The server no longer uses message passing for log events, making them faster and reduce memory consumption, and arrive more reliably in the debugger output.
  • Logging now avoids object[] allocations and boxing for formatted strings with up to 6 arguments when the used log level is not enabled. Is<Level>Enabled can be used to also skip resolving expensive arguments.
  • The compile-time METAPLAY_LOG_LEVEL_<level> switches now work the same on the client and the server, and across all the IMetaLogger based logging methods.
  • Client logging is now more robust against logging from background threads after the SDK has been deinitialized.
• Communicate entity import processing errors appropriately.
• TimelineHistory now only tracks the model tick/action history when the timeline debugger window is active.
• Significantly optimize domain reload speed in Unity Editor.
• Fix errors from background thread logging after the SDK has been deinitialized on the client, e.g., from the incident report uploader.

Notable Documentation Changes

• Subscriptions and data fetching documentation have been re-written to cover the new API and more advanced use-cases: Fetching Data from the Game Server and Working with Subscriptions.
• The Managing Broadcasts and the Managing Push Notifications documentation have been refreshed.
• Several pages have been updated following quality-of-life improvements in the SDK or rewritten for overall clarity, including:
  • Introduction to Metaplay’s Programming Mode
  • Introduction to Metaplay's Programming Model has been superseded by Getting Started
  • Tutorial: Game Configs
  • Deep Dive: Game Logic Execution Model
  • Development-Only Features
  • Client and Server Listeners

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

Change Log

Breaking

• Removed the deprecated tests.py integration tests.
  • Action Required: Use the new better dockerized integration-tests.py instead.
• Upgraded Metaplay to use .NET 7.
  • Action Required: Upgrade all your C# projects to use <TargetFramework>net7.0</TargetFramework>.
  • Action Required: All build systems, CI pipelines, etc. must be upgraded to .NET 7 as well.
• Renamed GameLogicPath to SharedCodePath in C# projects and Directory.Build.props files.
  • Action Required: Replace all usage of GameLogicPath in your .csproj files with SharedCodePath.
• SegmentedIOBuffer no longer has a contructor taking in the MemoryAllocator. It will now use the Memory Pool if available.
  • Action Required: Remove allocator argument from new SegmentedIOBuffer(...) calls.
• Players will no longer join the player leagues automatically on startup. This is now done by calling TryJoinPlayerLeagues in the player actor.
  • Action Required: If using leagues, add a call to TryJoinPlayerLeagues in the game's PlayerActor.
• Removed the PlayerActorBase._currentAssociatedPlayerDivision property.
  • Action Required: Use the CurrentDivision property stored in Model.PlayerSubClientStates[ClientSlotCore.PlayerDivision] instead.
• Renamed UInt128 to MetaUInt128 to avoid confusion with System.UInt128 (introduced in .NET 7).
  • Action Required: Replace any usage of UInt128 with MetaUInt128.
• FlatIOBuffer no longer has a contructor taking in the MemoryAllocator. It will now use the Memory Pool if available.
  • Action Required: Remove allocator argument from new FlatIOBuffer(...) calls.
• LoginProtocolVersion is no longer configurable
  • Action Required': Replace MetaplayCore.Options.LoginProtocolVersion with MetaplayCore.LoginProtocolVersion
  • Action Required': Remove loginProtocolVersion from new MetaplayCoreOptions constructors.
• The server option InAppProductionMode in section AppleStore has been renamed to AcceptProductionPurchases.
  • Action Required: If any of your Options.*.yaml files specify this option, rename it there.
• Dashboard: The subscription module's interfaces have changed. The built-in subscriptions were moved into the core module.
  • Action Required: Update any custom subscriptions to use the new interfaces as well as any custom dashboard components that call the subscription API.
• Synchronous FileUtil methods are removed from WebGL builds.
  • Action Required: If WebGL build fails due to a call to such a method, the call site should be inspected. If the file access is needed in WebGL, async API should be used. If file access is not needed, the call should be conditionally disabled in WebGL.
• Logging has been simplified to use IMetaLogger and the compile-time defines names are now METAPLAY_ prefixed.
  • Action Required: If using the old COMPILE_LOG_LEVEL_XYZ, switch to use the equivalent METAPLAY_LOG_LEVEL_XYZ instead. Note that INFO is now INFORMATION.
  • Action Required: Replace any use of LogLevel.Info with LogLevel.Information.
• The Dockerfile.botclient has been removed as Dockerfile.server now includes the BotClient.
  • Action Required: Update the metaplay-loadtest Helm chart to v0.3.0 or later.

Added

• SDK: Added the ability to override a league's normal recurring scheduling with a custom schedule.
• SDK: Added member InAppPurchaseEvent.PaymentType, which can be used to check if the purchase was a normal real-money purchase or a sandbox (test) purchase. This is available after the purchase has been validated. For Google Play, this involves an additional request to the Android Publisher API, and thus requires that a service account for accessing the Android Publisher API has been configured on the server (otherwise PaymentType will remain null).
• SDK: Added CsvReader.ReadStruct() variant that parses struct members from key-value string stream.
• SDK: Added helper method CsvEntryBuilder for reducing boilerplate when dealing with CSV config files in the GetEntryBuilder() method in a custom config builder.
• Unity: Add custom build preprocessor which allows specifying custom scripting #defines via a METAPLAY_UNITY_DEFINES file at the project root. Useful for forcing specific environment in CI jobs. Only supported in Unity 2021.2 and newer.
• Unity: EditorTask utility for launching long running tasks in Unity editor, used by game config building in the samples.
• Unity: Added 'Copy value to clipboard' functionality to the Model Inspector.
• Server: Add support for reading Runtime Options as base64-encoded yaml from an Environment variable. Such sources are declared with env-yaml-base64:VARIABLE_NAME path.
• Dashboard: Added audit log events for leagues and divisions.
• Dashboard: Added the ability to manually advance a season in the league manager.

Changed

• Dockerfile: Retain the relative project structure within the docker builds to loosen the requirements for how the SDK and project can be placed relative to each other.
• Dockerfile: Simplify the C# builds by removing the separate *.csproj copying and dotnet restore.
• Server: Remove the #defines for TRACE and DEBUG from the C# project files. These are automatically defined by the build tools.
• Server: Renamed InternalPlayerDivisionJoinRequest to InternalPlayerDivisionJoinOrUpdateAvatarRequest to better reflect the intended usage.
• Server: CORS policies can now be assigned for each authentication domain using the [EnableCors()] header on the root controller.
• Server: On server startup, the critical CDN resources of the currently active GameConfig and Localizations are reuploaded if they are missing. This allows moving server and its state to another environment without needing to also manually bring in CDN state.
• Server: More aggressive sanitization of user supplied paths in log messages.
• Sample projects: Use rollForward = latestFeature in global.json files so that the latest feature-band gets used (eg, 7.0.2xx).
• HelloWorld: Put all the code under Metaplay.Sample namespace to avoid conflicts with userland code and to better communicate that the code can be adapted or removed.
• SDK: Minimum required Unity version is now 2020.3.
• SDK: DebugLog in Unity now logs with the correct log level, when possible, according to the logging method used. Unity does not have Verbose and Debug log levels, so for those the basic log level (same as Info) is used.
• SDK: Added server option AppleStore:AcceptSandboxPurchases which controls whether App Store sandbox IAPs are accepted; it is no longer controller by InAppProductionMode (now called AcceptProductionPurchases) being false. AcceptSandboxPurchases defaults to false in production and to true elsewhere, which retains previously-existing default behavior. You may choose to set it to true in all environments if you wish to always accept valid App Store sandbox IAPs in order to allow TestFlight users to perform sandbox purchases without needing to mark them as developers in the dashboard.
• SDK: Localizations are now stored compressed in CDN and client cache.
• SDK: Synchronous FileUtil methods are removed from WebGL builds.
• SDK: Logging simplification and optimizations:
  • All logging (client and server) should now use the IMetaLogger interface.
  • The server no longer uses message passing for log events, making them faster and reduce memory consumption, and arrive more reliably in the debugger output.
  • Logging now avoids object[] allocations and boxing for formatted strings with up to 6 arguments when the used log level is not enabled.
  • Prefer Information over Info to align with Microsoft's naming conventions.
  • Remove various old adapter classes. Gets replaced by IMetaLogger.
  • MetaReceiveActor now has a _log member to reduce code duplication.
  • Client no longer has a separate PreInitLogger as UnityLogger now works before log levels have been initialized, making it more robust against threading race conditions.
  • The compile-time METAPLAY_LOG_LEVEL_<level> switches now work the same on the client and the server, and across all the IMetaLogger based logging methods.
• SDK: Communicate entity import processing errors appropriately.
• SDK: GameConfigHelper.ParseCsvToSpreadsheet now removes trailing empty cells from each row. In particular, rows with nothing but empty cells will produce output rows with 0 cells. This behavior is more in line with Google Sheet fetching.
• SDK: Notification content changed to a type that uses LocalizedString to align with mails and broadcasts, allowing the use of MetaGeneratedForm. Migrates existing NotificationCampaigns in DatabaseScanCoordinatorState.
• Unity: TimelineHistory now only tracks the Model tick/action history when the Timeline Debugger window is active. Optimize the timeline's memory allocations: it no longer allocates when not active and re-uses memory when it is active.
• Unity: Optimize domain reload speed in Unity Editor.
• Dashboard: The subscription system has been re-written in Vue 3 primitives for significantly improved performance when handling large data structures. Use the new useStaticSubscription and useDynamicSubscription composables to subscribe to data.
• Dashboard: Migrated multiple components from the Options API SFC based syntax to the Composition API Setup based syntax.
• Dashboard: The NotificationForm and BroadcastForm components have been replaced by the NotificationFormButton and the BroadcastFormButton respectively to take advantage of our custom MetaActionModalButton modal component for more consistent modal behaviour. The files and related components have also been rewritten to use the Composition Api setup syntax.
• Dashboard: Notification forms and views now use MetaGeneratedForm to display localized content.

Fixed

• SDK: WebConcurrentDictionary now matches System.ConcurrentDictionary behaviour in the case of dictionary being modified during value creation in GetOrAdd().
• SDK: The client-side WebGL pitfall code analyzer no longer warns about the usage of ContinueWith when using an explicit TaskScheduler argument.
• SDK: Dynamic creation of StringId interned values for types that are not tagged MetaSerializable now works correctly.
• SDK: Fix errors from background thread logging after the SDK has been deinitialized on the client, e.g., from the incident report uploader.
• SDK: Fixed PlayerModel.DeviceHistory[].LoginMethods potentially containing null login method.
• Unity: Fixed Model Inspector footer overlapping and hiding rows of the tree view.
• Unity: Fixed Model Inspector search results not respecting active filters.
• Unity: Model Inspector now shows the name of enum members instead of their numeric value.
• Server: Creating new EFCore migrations now longer prints IHost errors and warnings.
• Server: Using InternalPlayerDivisionJoinOrUpdateAvatarRequest to update the division avatar of an existing player after a division has concluded no longer results in an InvalidEntityAsk error.
• Server: The local development VueCorsPolicy now only applies to the AdminApi endpoints instead of all the HTTP endpoints.
• Server: Removed potential LOH allocations in HttpUtil when Http request returned non-200 response with a long error message.
• Server: Fixed the /gracefulShutdown to expect a HTTP POST request instead of GET.
• Server: If server is no longer compatible with the current game config, it will fall back to the config it the server was built with instead of failing to start the server.
• Server: FileUtil.DeleteAsync() now works also on server builds.
• Dockerfile: Fix skipping of Cypress installation in non-test builds.
• Dashboard: Significantly reduced browser memory pressure on pages with a lot of components and large data structures, such as the player details page.
• Dashboard: Fixed search function for user permissions on the My Profile page.
• Dashboard: Links to Grafana logs no longer auto-inject the JSON decoding as part of the log processing as logs are generally plain-text.
• Dashboard: Fixed and improved searching and filtering on Analytics Events list page.
• Dashboard: Fixed sidebar entries not always highlighting the active route correctly.
• Dashboard: Fixed segment targeting in the MessageAudienceForm where the segments were listed incorrectly when editing or duplicating an existing broadcast.
• Dashboard: Fixed a bug that would cause the game config contents UI to fail to render when an experiment is selected and that experiment adds new array items.