Highlights

• New feature: IAP Subscriptions support makes it easy to implement recurring real money subscriptions that can be bought from multiple stores, such as Google Play and Apple’s App Store.

• Major improvement: TypeScript Support and much faster (over 20x) development server in the LiveOps Dashboard! We will be migrating our core libraries to TS over the next few releases.
• New preview feature: Async Matchmaker base-actor added to the SDK. This can be used to implement your own matchmaker for asynchronous multiplayer gameplay. If you would like to adopt this, please talk to us!
• New preview feature: Multiplayer Entities allow faster and easier implementation of multiplayer features with an entity actor on the server and an entity model that is synchronized across all the participating clients. If you would like to build on this preview feature, please talk to us!
• Major improvement: Unity Editor Integration has been revised to streamline iteration times and game builds. In particular:
  • The Metaplay SDK now fully supports entering and exiting editor play mode without domain reload and associated SDK reinitialization. To enable this optimization for your project see the Unity documentation at https://docs.unity3d.com/Manual/DomainReloading.html.
  • The generated serializer assembly Metaplay.Generated.dll for game builds no longer interferes with editor operation and therefore a failing or aborted game build leaving this temporary file in the filesystem is no longer an issue.
  • Script compilation no longer statically depends on the generated serialization code which fixes script compilation outside of the actual game build (e.g. in the Unity addressables build).
  • Client builds with Mono scripting backend are now supported, but heavily discouraged due to performance tradeoffs.

Breaking Changes

• The LiveOps Dashboard dependencies have been updated.
  • Action required: Please run npm ci to fetch the new (audited) dependencies before running the project locally.
• The version of the client-server WireProtocol has been bumped up to version 10, to eliminate legacy project-specific differences in the low-level protocol. To facilitate a smooth game update release 17 introduced client-side forwards compatibility to version 10, so as long as released clients are based on Metaplay R17 this change is transparent.
  • No action required: Older clients are already compatible with WireProtocol version 10.
• The fixed-point math library was updated and some of the methods were changed to produce different results in edge cases.
  • Action required: Easiest is to bump LogicVersion and update the game client and server synchronously.
• The configuration of how entities are run on the server is now done with the [EntityConfig] attribute on a SomeEntityConfig class. See below for details.
  • No action required: All existing entities have been ported to the new system.

Notable LiveOps Dashboard Changes

• The dashboard project has been migrated from vue-cli and webpack to vite and rollup. This is a major refactoring that got us much faster development server speeds, fewer dependencies, simpler configuration, and TypeScript support.
• The migration to vuex-based state handling is now complete and all references to the deprecated globalState object have been removed. This gives us access to the great debugging tools from the Vuex team.
• A new landing page for fresh dashboard users with no permissions.
• The browser now reloads the dashboard when publishing a new config to "activate" it immediately without manual reloads.
• The experiments gained a new option to disable the rollout of an ongoing experiment while keeping it live for everyone who already previously enrolled.

• The experiment rollout forms got upgraded to our new, smarter form components with more advanced validation and helpful feedback.

• In the Audit logs, a user’s own email address now appears in green to highlight their actions.

• Languages are displayed using the full language name instead of the ISO language code.

• Runtime options now include descriptions for each configuration class and option value. This provides a quick and easy reference whenever you would like to use a specific option.

• Added an action for force-resetting player state when the player state can’t be deserialized for viewing. The “force reset” button is shown in the player details error dialog. This should be used as a last resort only and is mainly intended for development environments!

Notable Under-the-Hood Changes

• Upgraded to .NET 6.0.3 (and SDK 6.0.201).
• The EntityArchive format used for exporting and importing entity states now supports communicating the schema version of the entity and importing an entity of an older schema version will automatically trigger migration code to be run on import. This can be used to import entity states across environments that are running different schema versions, for example importing a player from production to a development environment where the schema has been updated.
  • Note: the dashboard diff view in the entity import dialog shows the diff prior to running migrations to the imported model!
• Database item counts are more accurate as exact item counts are now queried. The queries can take a while, so they are only performed once every 15 minutes and values may therefore be slightly out-of-date.
• Performance and memory optimizations:
  • Improve the serialization speed on the server by about 2x. On the client, performance was improved by 10-15%.
  • On Unity 2021.2 and above, Span<> optimizations are used to avoid memory allocations during serialization on the client.
  • Generating and compiling the serializer code is now about 10-15% faster.
  • Improved Docker build speeds by avoiding unnecessary work.
• Upgraded the included FixPointCS fixed-point library to v0.3 with the following changes:
  • Performance improved by 5-25% due to various optimizations & more aggressive inlining.
  • Constructors were replaced with explicit static FromXyz() methods to avoid accidental implicit casting.
  • Fix the GetHashCode()s to XOR the integer and fraction parts (instead of bitwise ORing the high and low parts).
  • Breaking: Pow(x, 0) now always returns 1 for any values of x.
  • Breaking: SqrtPrecise() now returns 0 for invalid values (previously returned -1).
  • Add configurable callbacks for handling invalid inputs to methods: default implementation doesn't do anything.
  • Some new helper methods, e.g., Ratio10(), Ratio1000(), Div2(), Sign(), ..
  • Fix integer-valued F32s having O(n) insert when used as keys in OrderedDictionary<> due to GetHashCode() generating conflicts for integer values.
• The new [EntityConfig] attribute and system consolidates the configuration of entities in the server: which actors should back the entities, how to shard them in the cluster, and so on. This replaces the old configuration in ServerMain.cs and the old [EphemeralEntityActor(..)] and [PersistedEntityActor(..)]. There is no proper documentation for this yet as further work will be done in the area, but take a look at the SDK actors for usage examples.
• Changed Docker dashboard builds to only use pre-audited LiveOps Dashboard dependencies instead of the latest compatible ones.
• The default path for client/server shared source files is now Assets/SharedCode/. The directory can be changed from the Directory.Build.props and given as an argument to docker builds.
• The backend Dockerfiles and CodeAnalyzers.csproj have been promoted into the SDK, streamlining the SDK upgrades for them.
• Added a new unit test project for Metaplay.Server types to increase SDK test coverage.
• Generated Forms validators can now be defined in Interfaces.
• All JSON objects returned from the API now contain a $type property to make adding new generated views easier and more consistent.
• Added support for logging in to the game server with social authentication credentials directly, useful for authentication platforms that provide credentials management. The change to the login handshake protocol is backward compatible and none of the provided core authentication platforms make use of the direct login feature.
• Add support for persisting the player state when running in Offline Mode. You can enable it by passing OfflineOptions = new MetaplayOfflineOptions { PersistState = true, SupportedSchemaVersions = MetaVersionRange(1, 1) } in MetaplayClientOptions to MetaplayClient.Initialize(), or in MetaplaySDKConfig to MetaplaySDK.Start(). Check out Idler for an example.
• Server start is now visualized in Metaplay Server Dashboard in Grafana to make it easier to know if anomalies were caused by a deployment.

• New experimental GameConfigTool that can be used to build, print, and publish (to localhost only for now) Game Configs with a command-line app. This can be useful for, eg, easier debugging of Game Config builds within Visual Studio. If you wish to try out the tool, you’ll need to apply your project-specific secrets, sheet ids, etc. in GameConfigTool.cs.
• SDK now uses the new IntegrationRegistry system for discovering game-specific overrides for SDK API classes related to in-game mails and game configs. Over time this system will be adopted to cover further integration APIs. The system reduces the need for custom hooks for introducing game integration classes.

Version Compatibility

Infrastructure and Helm chart compatibilities for this release:

• Minimum version requirements
  • Requires infra-modules version 0.1.6 or later for infrastructure
  • Requires metaplay-gameserver Helm chart version 0.3.1 or later for deployment
• Suggested versions
  • Recommended infra-modules version 0.2.0 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.3.2 or later for deployment

Change Log

Added

• Dashboard: Users who connect to the Dashboard without any assigned roles now get a message to contact the administrator.
• Dashboard: The project now supports TypeScript!
• Dashboard: Players that are online but the app is paused have amber presence indicator instead of green.
• Dashboard: Added a new meta-language-label component to display language labels.
• Dashboard: Added new meta-input-number and meta-input-checkbox components as we start to migrate away from Bootstrap components.
• Dashboard: Added a new card in the player details page to view and manage the new IAP subscriptions.
• Dashboard: Added descriptions to the RuntimeOptions classes and values.
• SDK: New EntityActorRegisterCallback method attribute for EntityActor classes to receive EntityActor metadata as part of the EntityActorRegistry initialization.
• SDK: Support auto-renewing subscription IAPs. The server checks subscription renewal after the initial purchase.
• SDK: For Google Play IAPs, store OrderId (in addition to TransactionId == PurchaseToken) in the IAP history.
• SDK: Added EntityActor.ScheduleExecuteOnActorContext helper for cancellable, short-term actor-local scheduling needs.
• SDK: Added support for logging in with Social Authentication credentials using the new SocialAuthenticationLoginRequest login message.
• SDK: Centralized integration registry for maintaining game integrations for API classes (supports singleton and default constructible integration API classes).
• SDK: Server now checks all necessary DbSet<>s are declared for all PersistedEntityActors at application launch time instead of upon first use.
• SDK: AsyncMatchmakerActorBase that games can derive from to create matchmaker actors for async matchmaking needs.
• SDK: Player force reset functionality to be able to clear player state when reading the current player state fails.
• SDK: Support for persisting the player state in Offline Mode, only intended as development tool for now.
• SDK: Improved tooling for creating new Multiplayer Entities: PersistedMultiplayerEntityActorBase, MultiplayerModelBase, and MultiplayerEntityClientBase provide base code for server-side ticking entities, and for their Model and the client side state management.
• SDK: Server now emits on launch metaplay_build_info metric that contains build number and commit id.
• Idler: New experimental command-line GameConfigTool that can be used to build, publish (to localhost for now), and print the contents of Game Configs from outside Unity.

Changed

• SDK: Upgraded to .NET 6.0.3 (SDK 6.0.201), which addresses some known vulnerabilities.
• SDK: Moved tracking of live entity counts and recently active entities into StatsCollector.
• SDK: New GameConfigs in Server's GameConfig history are now stored in compressed format.
• SDK: Require GameConfigLibrary<TKey, TInfo> key type to implement IEquatable<TKey> to avoid potential performance pitfalls.
• SDK: StringId<> class is now abstract.
• SDK: Disallow by default non-empty [MetaSerializable] types that have no serializable (i.e. [MetaMember()]) fields as they are most likely an error.
• SDK: Entity archive exports now contain the schema versions of the exported entities and importing entity archives supports running migrations on the imported models.
• SDK: Removed DatabaseShardState as obsolete.
• SDK: Replace old database item count estimations with new APIs MetaDatabase.GetTableItemCountsAsync() for querying exact counts (can take time) and MetaDatabase.EstimateTableItemCountsAsync() for quickly getting estimates.
• SDK: Replace the old [EphemeralEntityActor] and [PersistedEntityActor] attributes with a more general [EntityConfig] attribute and classes for specifying how the EntityKinds should behave on the server.
• SDK: Rename LogicVersionRange to MetaVersionRange. Use it for specifying PersistedEntityConfig.SupportedSchemaVersions.
• SDK: Cleanups to Dockerfiles to reduce divergence: don't rely on .sln files, target dotnet operations against specific project, and use more explicit paths.
• SDK: Optimize docker builds by skipping unnecessary build and restore steps. Drop unit tests as they're replaced by CI jobs.
• SDK: Updated the client SDK init/deinit code to properly support tearing down state on Editor playmode exit. This allows projects to disable domain reloading on playmode transitions for faster iteration times.
• SDK: Don't generate the serializer DebugStream append code by default. Speeds up serializer generation by about 0.5s in HelloWorld.
• SDK: Split server runtime option EntityEventLog by entity type into EventLogForPlayer and EventLogForGuild. This reduces nesting in the options, allowing them to better benefit from validation as well as the new [MetaDescription]s for options.
• SDK: Upgrade FixPointCS to v0.3: switch from ctor to static FromXyz(), backward-breaking changes to Pow(x, 0) and SqrtPrecise() for negative values, callbacks for invalid inputs (disabled by default), some new helper methods, improved performance.
• SDK: Byte buffer representation in IOBuffers is simplified which improves serialization performance by 10-15% in microbenchmarks.
• SDK: Migrate CodeAnalyzers project into the SDK.
• SDK: Improve serializer speed on the server by about 2x by inlining some methods.
• SDK: Dockerfiles are now part of the SDK, to enable easier merging of updates for them.
• Dashboard: User page now only shows roles that are relevant to the active deployment and removes the deployment prefix string to make them easier to read.
• Dashboard: Highlighted own username in audit logs and other pages.
• Dashboard: Major refactoring of the project bundler and development server from vue-cli to Vite.
• Dashboard: utils.js refactored to named exports in individual files to make individual named imports and thus, tree shaking, possible.
• Dashboard: Replaced assumed role input with a checkbox selector.
• Dashboard: Changed the integration dashboard tests to run against the production build, served by the game server.
• Dashboard: Major refactoring of dashboard core code from vanilla JavaScript into TypeScript. Ongoing effort.
• Dashboard: Completed the refactoring of all state management into Vuex that was started during R17. this.$root.state is no more!
• Dashboard: Refactored NPM scripts that depended on environment variables into their own new utility tool to get rid of one deprecated dependency.
• Dashboard: Added ability to pause rollout of experiments.
• Dashboard: All IAPs are now listed in a single card instead of two to make room for the new subscriptions card.
• Dashboard: All objects returned from the API now include a $type property by default.
• Dashboard: Generated views can now use the $type property included in objects to dynamically infer the type of the object.
• Dashboard: Generated forms boolean fields now default to false.
• Dashboard: Reworded the logic version redirect dialogue to be more specific about how it works.
• Dashboard: The browser now reloads the dashboard when publishing a new config to "activate" it immediately without manual reloads. The intention is to make this less intrusive in future releases.
• Unity: The generated serializer assembly Metaplay.Generated.dll no longer needs to be manually deleted after a game build. The file has been moved from under Assets/Metaplay to Assets and is automatically cleaned up on a successful build. A failed or aborted build will result in the file not being deleted but the existence of it no longer interferes with Editor operation.
• Unity: Network thread log messages are now written to log even if even main loop is stalled. Buffered messages are forcibly flushed after 5 seconds if main thread is not responsive.
• Unity: The generated serializer assembly Metaplay.Generated.dll is now loaded dynamically in game builds as well. This removes the static dependency on generated code and allows scripts to be build outside of the main player build flow, including Addressables builds from editor.
• Unity: Enable usage of Span<> in Unity 2021.2 and above for various serializer code paths, reducing the number of allocations during (de)serialization.
• Sample projects: Upgrade to Unity version 2020.3.29f1. Upgrade Unity dependencies.
• HelloWorld: Use 'en' as the default language instead of previous 'none'.
• Idler: Enable player state persistence in Offline Mode.

Fixed

• SDK: The serializer now allows types in different namespaces to have the same name.
• SDK: Better error messages for when GameConfigLibrary<> key type is missing either ToString() or Equals().
• SDK: Replace some usage of deprecated UnityWebRequest with HttpClient to avoid deprecation warnings.
• SDK: Metaplay primitives that implement IComparable<> now also implement untyped IComparable.
• SDK: Serializer private member access now works when building with Mono scripting backend.
• SDK: The database item counts shown in the dashboard and used for estimations of segment sizes etc., are now more accurate, but are only updated every 15 minutes due to the operation being fairly expensive.
• SDK: Copy the .editorconfig in Dockerfiles to silence some benign warnings in docker builds.
• SDK: For Google Play purchases, the server validation now checks that the purchase is in the "purchased" state (purchaseState = 0). In particular, don't accept Google Play's "deferred" purchases until they are completed.
• SDK: For Google Play purchases, the client-side IAPManager utility now ignores purchases in the "deferred" state (purchaseState = 4).
• SDK: Don't log errors on the server when a large incident report is sent by the client at session start failure.
• Dashboard: The number of Concurrents shown on Overview page no longer counts clients that have not yet completed session handshake. This fixes the confusingly high number when Maintenance Mode is enabled.
• Dashboard: Fixed guild pages not having header icons (broken route meta data object).
• Idler: Configuring backend gateways in DeploymentSpec no longer allows overriding EnableTLS but will use the value from the primary configuration.