Highlights

• New feature: Model Inspector allows you to inspect Metaplay Models in real-time in the Unity Editor. Open the Model Inspector window from the dropdown menu: Metaplay / Model Inspector. See the documentation at Model Inspector to get started!

Use the Model Inspector window to view your game Models in a convenient way.

• New feature: NFT Support allows modeling NFTs as C# classes, tracking players' NFT ownerships, and mapping in-game NFT objects to and from public NFT metadata files. See Getting Started with NFTs for a guide.
• Major improvement: WebGL Support is now considered stable. With the addition of localization and incident report support, WebGL has reached feature parity with other platforms. See the Metaplay & WebGL for more information.
• New preview feature: Leagues allows you to add seasonal competition in your game, with local division leaderboards and seasonal rewards. If you're interested in adding this to your game, shoot us a message! See the quick-start guide at Quickstart Guide.

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 OverviewListItem integration hook has been refactored into a class and now provides helper functions to easily add custom content to the list.
  • _Action required: Update calls to add<listName>OverviewListItem to use the helper functions.
• All elements in the player details page have been migrated to subscriptions to guarantee consistent data refreshing on the page. The previous @refresh event has been removed._
  • Action required: Please make sure all your custom admin actions and cards also use subscriptions and call the triggerRefresh function of the subscription as needed.
• Two deprecated properties have been removed from the dashboard's addPlayerRewards integration API to make it simpler.
  • Action required: Update your calls to addPlayerRewards. The compiler should give a helpful error.
• Removed custom Cypress test navigation commands in favour of using cy.visit() directly.
  • Action required: Replace any calls to cy.navigateToPlayer(), cy.navigateToOverview(), cy.navigateToSystem() and cy.navigateToSidebarPageByName() with cy.visit().
• NFT support has been extended and modified since the Web3 preview releases (20+Web3, 20.1+Web3).
  • Action Required: If your project is using the NFT features from the preview release, you will need to update your C# code and server options. Please see Getting Started with NFTs for details.

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

• The player details page has been split into sub-tabs. The individual tabs can be customized, deep-linked to and make the resulting page faster to load. To get started, have a look at the Configuring the LiveOps Dashboard page.

Tabs make browsing large player details pages easier!

• You can now globally pause (and resume) all ongoing database scan jobs. The scan jobs page has also been redesigned for consistency and legibility.

Is something unexpected happening with the database load? Pause the ongoing jobs to investigate!

• The global error notifications now show more detailed error messages from the game server. This makes debugging API responses a lot more convenient.
• Many dashboard action modals have received upgrades with nicer error handling and a loading state. This should also fix cases where it was possible to submit a dialog multiple times by clicking very quickly.
• The game config and experiment detail pages performed poorly if you had large game configs and or a large number of experiments. The performance of these pages has been greatly improved in this release. UI changes have also been made to these pages so that they are easier to navigate.
• The PlayerOverviewCard title and subtitle have been split into sub-components to make it easier to override the default content with a custom component.
• Entity event streams can now be paused. This makes it easy to, for example, search through the latest player events without new events disrupting your flow.

Want to look at a player's events but new ones keep scrolling in? Now you can pause the stream.

Notable Under-the-Hood Changes

• New MetaActionModalButton UI component makes it easier to create consistent and high quality buttons that spawn modal pop-overs. A very common use-case in custom dashboard pages.
• Added a new PlayerResourcesList component on the PlayerOverviewCard. This allows you to easily add custom content or override the default list view with your own custom component.
• New MetaActionModalButton component to make it easier to create buttons that spawn modal screens. These modals now show a loading indicator and error messages from the resulting API request.
• Added a new MetaAlert component to make it easier to create consistent looking alert messages.
• MetaPageContainer component now has a slot and a property to show optional alerts on the page with consistent formatting. This reduces page layout copy/paste.
• MetaPageContainer component also got new slots like overview and center-column to make it easier to create consistent-looking pages. All core views have been migrated into using this component.
• Added support for unit tests in the LiveOps Dashboard project using Mocha and Chai. A test code coverage report is also included by NYC. The tests are automatically run as part of the build process or can be run manually with npm run test:unit. See Dashboard Testing to get started with writing your own.
• Cypress tests now support TypeScript. All core tests and configuration have been migrated. The game-specific tests have typings for our custom commands to get code completion and type checking.
• Added new component entry points to various dashboard pages. You can add, remove or replace default components with custom components using the addUiComponent or removeUiComponent hooks. More information about these hooks including examples can be found through your IDE.
• The METAPLAY_ENABLE_GUILDS preprocessor define that was previously required for using Guilds functionality has been removed, and the Guilds feature is now runtime-enabled in GlobalOptions.
• Adding custom entries to the player analytics context is now supported via a game-side PlayerAnalyticsContext class.

Notable Documentation Changes

• Refreshed the Working with the LiveOps Dashboard HTTP API documentation with up-to-date code samples.
• Added a new section about re-naming player tabs to the Configuring the LiveOps Dashboard page.
• Updated the Customizing the LiveOps Dashboard Frontend with more information about modifying the dashboard using the UiPlacement system.
• Updated the Using Meta-Components page with information on the MetaUi module.
• Updated the Database Scan Jobs page with new information on the updated scan jobs LiveOps Dashboard tools.

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.2 or later for deployment
• Suggested versions
  • Recommended infra-modules version 0.2.6 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.4.4 or later for deployment

Change Log

Breaking

• SDK: MetaplaySDK/CloudCore is renamed to MetaplaySDK/Cloud. SDK C# projects now start with Metaplay. prefix.
  • Action Required: Project references to MetaplaySDK/Cloud must be updated.
• SDK: Guild and other non-Player entity model FastForwardTime is removed and replaced with OnFastForwardTime, which is called after the model clock is already fast forwarded.
  • Action Required: Each FastForwardTime should be renamed to OnFastForwardTime and should no longer modify clock and instead assume clock is already updated.
• SDK: METAPLAY_ENABLE_GUILDS has been removed in favor of the new METAPLAY_DISABLE_GUILDS, by default the SDK now compiles with guilds code included. Remove any traces of METAPLAY_ENABLE_GUILDS in integration code unless there are explicit reasons to disable guilds code compilation in the project.
• SDK: MetaTime.ToLocalDateTime has been removed as it is misleading and not safe to use in shared game logic, since its result depends on the machine it is executed on.
  • Action Required: Existing usage in game code should be reviewed. Shared code should calculate local times using playerModel.TimeZoneInfo.CurrentUtcOffset instead. Legitimate usage, if any, of MetaTime.ToLocalDateTime should be addressed either by adding it as a game-specific extension method, or inlining as metaTime.ToDateTime().ToLocalTime().
• SDK: MetaplaySDK.LocalizationManager and IMetaplayLocalizationDelegate APIs have been simplified:
  • Action Required: LocalizationManager.SetCurrentLanguage no longer takes in the version. Call-sites should no longer compute versions and pass it in.
  • Action Required: IMetaplayLocalizationDelegate.AutoFlags should be replaced with bool AutoActivateLanguageUpdates { get }. Old flag DownloadActiveLanguageUpdates is always enabled, DownloadSomeVersionOfAllLanguages is not supported.
  • Action Required: Following methods should be removed in IMetaplayLocalizationDelegate implementations: EnqueueSelectLanguageAction, OnLanguagesChanged, ValidateLanguage, GetAppStartDefaultLanguage, SessionContext, BuiltinFormat.
• SDK: api.system.maintenance_jobs permission has been renamed to api.scan_jobs.manage for consistency.
  • Action Required: Please update your custom roles as needed.
• SDK: MaintenanceJobSpec's abstract properties JobDescription and KindDiscriminator have been moved to the base DatabaseScanJobSpec, and the latter property renamed to JobKindDiscriminator and made optional (virtual).
  • Action Required: If you have custom DatabaseScanJobSpec types, they now need to implement JobDescription. If you have custom MaintenanceJobSpec types, their KindDiscriminator needs to be renamed to JobKindDiscriminator.
• SDK: DatabaseScanJobManager now has abstract method GetUpcomingJobs for reporting upcoming jobs to the dashboard.
  • Action Required: If you have custom DatabaseScanJobManager types, they now need to implement this method. At simplest, this may return an empty enumerable, but in that case the manager's upcoming jobs won't be visible in the dashboard.
• SDK: NFT support has been extended and modified since the Web3 preview releases (20+Web3, 20.1+Web3).
  • Action Required: If your project is using the NFT features from the preview release, you will need to update your C# code and server options. Please see the release 21 notes and NFT documentation for details.
• SDK: Default language is now defined in MetaplayCoreOptions and removed from GameConfig.
  • Action Required: MetaplayCoreOption constructor should define defaultLanguage. It is most commonly LanguageId.FromString("en").
  • Action Required: Default language is retrieved with MetaplayCore.Options.DefaultLanguage instead of gameConfig.DefaultLanguage.LanguageId.
• Dashboard: Global access to gameServerApi deprecated.
  • Action Required: Migrate your custom components to call useGameServerApi to get access to gameServerApi.
• Dashboard: Added helper functions for the OverviewListItem types to make it easier to add new items to the overview lists.
  • Action Required: TBD
• Dashboard: Removed two deprecated properties from the addPlayerRewards integration API.
  • Action required: Update your calls to addPlayerRewards. The compiler should give a helpful error.
• Dashboard: Removed custom Cypress test navigation commands in favour of using cy.visit() directly.
  • Action required: Replace any calls to cy.navigateToPlayer(), cy.navigateToOverview(), cy.navigateToSystem() and cy.navigateToSidebarPageByName() with cy.visit().

Added

• SDK: [MetaSerializable] attribute can be conditionally toggled with [MetaplayFeatureEnabledCondition] attribute. Serialization type data or code is not emitted for disabled features.
• SDK: PlayerModel.GetTimeOnTick(int) is removed. Time should be retrieved with ModelUtil.TimeAtTick(...) utility instead.
• SDK: MetaplayOAuth2Client configuration now defaults to Metaplay Managed Game Servers OAuth Provider.
• SDK: Guild and other non-Player entity model FastForwardTime is removed and replaced with OnFastForwardTime, which is called after the model clock is already fast forwarded.
• SDK: ModelJournal<> type no longer has the Action type as a generic argument. Actions are exposed as ModelAction base class.
• SDK: OfflineServer guilds implementation has been moved to the Idler sample OfflineServer implementation.
• SDK: The included Dockerfiles now perform an 'apt update && apt upgrade' to ensure the latest packages are installed.
• SDK: NFT support, including: modeling NFTs as C# classes, tracking players' NFT ownerships, and publishing NFT metadata to an S3 bucket. An earlier version was delivered to some customers in a previous preview release, but 21 is the first mainline release with these features.
• SDK: Sending push notifications now takes in optional Dictionary<string, string> Data which is delivered as the Firebase Messaging optional data.
• SDK: AnalyticsDispatcherSinkJsonBlobStorage can now be overridden by integration to override the json serialization of analytics events.
• SDK: The PlayerAnalyticsContext class can now be inherited by the integration to add game-specific player analytics context data.
• SDK: Added the Model Inspector, a Unity editor window that visualizes the real-time state of any Model.
• SDK: Added experimental Leagues support, with a sample integration in Idler.
• Dashboard: Core guild components migrated to subscriptions for their data fetching and refresh. This should fix potential guild-to-guild links not updating the page properly.
• Dashboard: Added object lengths into MetaRawData and changed preview font into monospace for legibility.
• Dashboard: Integration API split into sub-files for easier maintenance as the API grows.
• Dashboard: Tests now fail if they emit warnings or errors to the console. This can be disabled per-test if necessary.
• Dashboard: Improved API error component to include and copy-to-clipboard and stack display.
• Dashboard: Added a button to copy client logs from player incident reports.
• Dashboard: Added a new MetaActionModalButton component to make it easier to create buttons that spawn modal screens.
• Dashboard: Added a new PlayerResourcesList component to make it easier to add to or replace the default resources list on the PlayerOverviewCard.
• Dashboard: Added a new MetaAlert component to make it easier to create consistent looking alert messages.
• Dashboard: MetaPageContainer component now has a slot and and a property to show optional alerts on the page with consistent formatting. This reduces page layout copy/paste.
• Dashboard: MetaPageContainer component also got new slots like overview and center-column to make it easier to create consistent-looking pages. All core views have been migrated into using this component.
• Dashboard: Added unit tests to core modules.
• Dashboard: Added support for unit tests in customer projects.
• Dashboard: MetaPageHeaderCard and MetaListGroupItem now support an optional avatar parameter to display an image.
• Dashboard: Database scan jobs can now be globally paused and resumed.
• Dashboard: Added ability to pause entity event streams.
• Dashboard: Added PlayerOverviewTitle and PlayerOverviewSubtitle components to make it easier to override the default title and/or subtitle on the PlayerOverviewCard.
• Dashboard: Cypress tests now support TypeScript. All core tests and configuration have been migrated. The game-specific tests have typings for our custom commands to get code completion and type checking.
• Dashboard: Added new component entry points to the Players, Guilds, Matchmaking, Broadcasts, Scan Jobs and System details and List views. Using the addUiComponent or removeUiComponent hooks you can now add or remove custom components to these views.

Changed

• SDK: Upgraded to Akka.NET 1.4.46.
• SDK: IPlayerModelBase now implements IMetaIntegrationConstructible, mandating that an implementation is expected to be discovered during MetaplayCore initialization.
• SDK: Game config build no longer attempts to validate experiment variants that have no overrides associated to them.
• SDK: EntityActor now implements IEntityAsker interface that allows providing access to the entity ask mechanism to code outside of EntityActor classes.
• SDK: EntityArchive import and export from dashboard no longer does an extra hop through GlobalStateManager but communicates with EntityActor instances that are part of the operation directly.
• SDK: Server-side runtime caching of experiment-specialized game configs now retains each config for at least 20 seconds, with the intention of reducing resource usage (by avoiding unnecessary repeated config instantiation) in player maintenance jobs which wake up each player only for a short moment.
• SDK: Player state overwrite now preserves authentication and login history members by copying the values from the destination data instead of the auth reattach action.
• SDK: Optimized Util.ArrayEqual() to use SequenceEqual().
• SDK: Don't require running npm install to get Docker builds to work. The Dockerfile.server now runs npm install automatically if package-lock.json is not present.
• Dashboard: Changed header alerts to stick to the top of the screen for better visibility when scrolled down.
• Dashboard: Removed two deprecated properties from the addPlayerRewards integration API.
• Dashboard: Player resources list on the player details page now shows an error badge if the resource amount could not be resolved.
• Dashboard: The global backend error notifications now display more helpful messages from the game server.
• Dashboard: Greatly improved speed of game configs and experiments pages.
• Dashboard: Database scan jobs page has received an UI redesign.
• Dashboard: Reduced the length of some lists (eg: all experiments, all game configs) from 100 to 20 to make them more readable.
• Dashboard: Player exports now have the player ID in the file name when downloading as a file.
• Sample projects: Updated Unity version to 2021.3.14f1.
• Idler sample project: Nicer default values to in-game mail reward attachments.

Fixed

• SDK: Fixed a build performance regression introduced in R20.1, where Unity WebGL builds took an unexpectedly long time due to the generated serializer code containing a very large method. The large method is now split into multiple smaller methods.
• SDK: MetaplaySDK.PersistentDataPath is now available at all times in Editor which fixes the various clear/delete operations in the 'Metaplay' Editor menu.
• SDK: Refactor JSON converters that modified JsonSerializer state. Modifying the state in converters is not thread safe and can cause sporadic JSON serialization errors when JsonSerializer is used in parallel.
• SDK: In WebGL, fixed "TypeError cannot read property 'length' of null" error seen sometimes in logs during startup.
• SDK: Fix the security scan CI job to properly fail the job when vulnerable dependencies are found.
• SDK: Incident reporting now works in WebGL builds.
• SDK: Localization now works in WebGL builds.
• SDK: The SDK now includes a root-level .gitignore that overrides any patterns from the parent directories. Typical Unity .gitignores in the parent directory no longer cause SDK .csproj and .sln files to be ignored from git.
• SDK: Server/Client serializer protocol hash checking that was disabled in R20 has been re-enabled.
• SDK: Fixed bug in game config parsing for sheets that have multiple experiment variant override columns.
• SDK: BotClient now uses a random available port for its Akka.NET remoting to avoid conflicts on earlier port 7000 (the remoting is not actually used, but there seems to be no easy way to disable it).
• SDK: Log the actual internal exception from Model schema migration errors.
• SDK: JSON parsing of F32 and F64 now allows also JSON numbers without the decimal period.
• SDK: Reduced the probablity of hitting a rare Unity deadlock on IL2CPP if GC was issued while a background thread was initializing class static initializers.
• SDK: Initialize Serilog console loggers with CultureInfo.InvariantCulture to ensure locale-independent logging (fixes warning CA1305).
• SDK: On Editor, reduced the number of temporary Editor-specific allocations in Serialization code.
• SDK: Fixed rare race condition leading into session start failures if session start (loading a player) took exactly 1 + N * 5 seconds.
• SDK: Added [Preserve] attribute on DefaultOfflineServer to avoid it getting stripped in IL2CPP builds.
• SDK: The Javascript plugin metaplay-imx-link-sdk-plugin (used in web3-enabled WebGL client builds to interface with Immutable X Link SDK) is now included pre-built in the Metaplay SDK package to avoid needing to build it at client build time. The plugin is still only included in the client build if web3 features are enabled.
• SDK: Fix rare occurrence of client exceeding PlayerFlushActions.MaxTicksPerFlush ticks in flush batches.
• Dashboard: Fixed guild invites list to not show "X/0" as usage count for unlimited invites.
• Dashboard: Fixed player details page not always updating immediately after admin actions.
• Dashboard: Fixed the sidebar open/close button not having a hover state.
• Dashboard: Fixed the response reporting of the player social auth remove dialog.
• Dashboard: Fixed experiment control groups sometimes showing 0 participants instead of the actual count.

Release 21.1 (2023-01-13)

Breaking

• SDK: A new C# project MetaplaySDK/Backend/ServerShared/Metaplay.ServerShared.csproj has been added.
  • Action Required: Add a reference to this new project to your solution (.sln) files.
• SDK: Simplify ServiceShardingStrategy constructor to no longer require the ClusterConfig argument.
  • Action Required: Remove the argument from any call sites for the method.
• SDK: MetaplayApiController has been split to GameAdminApiController and MetaplayAdminApiController.
  • Action Required: Replace all inheritance from MetaplayApiController with GameAdminApiController.
• SDK: AdminApi permission requirements for controller endpoints are now specified with [RequirePermission(<permissionName>)] attribute.
  • Action Required: Replace all uses of [Authorize(<permissionName>)] with [RequirePermission(<permissionName>)] from your controllers.
• SDK: All API endpoints used by the LiveOps Dashboard must now specify the required permissions to avoid accidentally allowing anonymous access of endpoints.
  • Action Required: Specify [RequirePermission(<permissionName>)] for any endpoints missing them, or use [AllowAnomymous] to allow access by anyone who has access to the Dashboard.

Added

• The built-in web server (AdminApiActor) now properly supports multiple authentication domains. These are configured by implementing the AuthenticationDomainConfig for each desired domain. These classes can configure the type of authentication required as well as any additional services required.

Changed

• SDK: The database functionality has been moved to the Metaplay.ServerShared project to allow applications other than game servers use the functionality.
• SDK: The dashboard form generation code has been moved to the Metaplay.ServerShared project to allow applications other than game servers to use the functionality.
• SDK: The MetaDatabase class has been split to MetaDatabaseBase (in Metaplay.ServerShared) for the application-agnostic functionality and MetaDatabase for all game server-related functionality.
• SDK: MetaplayAdminApiController has been split from GameAdminApiController and has all the application-agnostic functionality.
• SDK: ServerOptions.WebRootPath is replaced by AdminApiOptions.WebRootPath.
• SDK: DefaultRole.cs is now in the Metaplay.ServerShared project.
• SDK: MetaDatabaseBase and MetaDbContext classes are now non-abstract to allow using it as the default implementation.
• SDK: AdminApiActor now uses more modern hosting APIs (CreateWebServerApp() instead of Host.CreateDefaultBuilder()) and enables use of MVC Views.
• SDK: The configuration of the /api HTTP endpoints (used by the LiveOps Dashboard) are now configured in AdminApiAuthenticationConfig instead of being hard-coded in AdminApiStartup (which is global to all types of HTTP endpoints).
• SDK: AnonymousAuthenticationHandler replaces old NoAuthMiddlewareHandler and implements role assumes by injecting them as claims into the HTTP request context.

Release 21.1+CId_Bugfix1 (2023-01-24)

Breaking

• SDK: PlayerModel internal representation of AuthenticationMethods has changed.
  • Action Required: If your game has custom authentication platforms, you MUST implement PlayerModel.FixupLegacyPlayerAuthEntry for them. Implementation may use convenience helper type PlayerAuthEntryBase.Default for the entries.

Fixed

• SDK: Fixed deadlock in localization download in WebGL builds due to missing poll checks.