Highlights

• Major improvement: State Persistence in Offline Mode has been made more robust and is now enabled by default. This allows testing of more complex scenarios in the offline mode, including player state migrations. The offline mode is still only intended for development purposes only.

• Major improvement: WebGL Support now includes networking via WebSockets and state persistence. It is now possible to build WebGL games using Metaplay. A few features are still missing and some manual configuration is required. See Metaplay & WebGL for more details.

• Major improvement: LiveOps Dashboard has been upgraded to Vue 2.7 and the project has been restructured to fully enable TypeScript. The new project structure now enables much more advanced customizations without changing the core SDK code. See Running the LiveOps Dashboard Locally on how to get started with the new project structure.

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 new Liveops Dashboard project structure requires a one-time manual migration of game-specific additions. Additionally, any imports from the core SDK need to be updated.

  • Action required: Have a look at the new Customizing the LiveOps Dashboard Frontend guide for how to get started with the updated integration APIs.

• Entity schema migration has been refactored to be cleaner, more robust, and to work in Offline Mode as well as when importing entities vie the LiveOps Dashboard. The configuration is now applied to the model classes (eg, PlayerModel) directly instead of the corresponding server-side actor class.

  • Action required: The schema migration needs to be migrated. See Entity Schema Versions and Migrations for more 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

• We have migrated to a new toast notification plugin and provided hooks for adding custom toast messages when a user completes an action. The toasts come in three flavors: success, warning and error.

• All overview cards have a new button to copy the page's ID to the clipboard for easy access.

• The broadcast overview card now has a new button to easily duplicate an existing broadcast.
• The player experiment card states have been updated to match the experiment detail page and now include a tooltip that explains the details of each state.
• The generated UI system has been refactored to TypeScript, and now supports more types like StringIds and MetaRefs.

Notable Under-the-Hood Changes

• Significant polish pass on all LiveOps Dashboard core APIs, their documentation and sample code coverage.
• Experiment variants can now be declared for entire columns at once. See Working with Experiments for more information.
• Entity schema migrations are now declared for the model classes (eg, PlayerModel) and can be executed without the corresponding PlayerActor. This enables running them in offline mode, and dry-runs when importing entities via the LiveOps Dashboard. See Entity Schema Versions and Migrations for more information.
• Metaplay backend components now include standalone .csproj files, to make the management of dependencies more explicit and to avoid inverse dependencies from the SDK code into the userland code.
• Runtime Options checks for nested items have been made stricter to help catch typos and incorrect settings as early as possible.
• Streamlined mapping of IPersistedEntity classes to database tables. The database schema generation now scans for classes implementing IPersistedEntity and automatically creates database table mappings for them, removing the need for adding entries in the MetaDbContext derived class. The old method of declaring database table mappings in MetaDbContext continues to be supported as well for backwards compatibility.
• Checked that the SDK-included IAPManager is compatible with Unity IAP 4.4.0. Note: Starting 2022-11-01, Google Play will start requiring that the Google Play Billing Library used in updates to existing apps be version 4 or newer. Unity IAP 4.4.0 is the first version that uses Billing Library version 4. Be sure to use Unity IAP 4.4.0 or newer, regardless of whether you're using Metaplay SDK's IAPManager or your own IAP management!
• Simpler game config build integration. The GameConfigBuildTemplate utility for configuring the game config build now provides default building of config entries for which no game-specifc build logic is required. The new GetEntryBuilder(Type configType, string entryName) API can be used to override the building of individual entries when per-entry customizations are needed. When no build customizations are needed at all, the integration no longer needs to provide a IGameConfigBuild class in the first place -- the SDK will default to using DefaultGameConfigBuild.
• Added parameter IRewardSource source to MetaPlayerRewardBase.InvokeConsume() for communicating information about the reward source to the consume function, when additional data is needed. The contents of the source information are up to the integration and are created by callbacks to the integration class MetaRewardSourceProvider.
• It is now possible to change a serializable concrete class to abstract without losing backwards-compatibility with existing serialized data. This is useful if you have a type that wasn't originally designed to be abstract but would now benefit from it. See Deep Dive: Data Serialization for more information.
• Experiment override values can now be declared by variant override columns in the game config sheet, in addition to variant override rows. The Working with Experiments chapter "Modify a single property of many rows via Variant Columns" describes how this is done.

Version Compatibility

Infrastructure and Helm chart compatibilities for this release:

• Minimum version requirements
  • Requires infra-modules version 0.2.0 or later for infrastructure
  • Requires metaplay-gameserver Helm chart version 0.4.0 or later for deployment
• Suggested versions
  • Recommended infra-modules version 0.2.3 or later for infrastructure
  • Recommended metaplay-gameserver Helm chart version 0.4.1 or later for deployment

Change Log

Breaking (list anything here that needs related changes in the customer projects)

• SDK: Server-side csproj files need to be updated to depend on the SDK projects.
• SDK: Server types are now found in assemblies prefixed with "Metaplay.". Dashboard type references might need to be updated to reflect this.
• SDK: GuildModel.Tick is now GuildModel.OnTick.
• SDK: The ASP.NET dependencies are now included in CloudCore.csproj instead of Server.csproj.
  • Action: All customer projects need to be updated.
• SDK: SupportedSchemaVersions has been moved to the respective persisted objects (eg, PlayerModel or GlobalState).
  • Action: The relevant models must specify the [SupportedSchemaVersions(oldestSupportedVersion, currentVersion)] attribute and the individual migration methods the [[MigrationFromVersion(fromVersion)] attribute.
• SDK: METAPLAY_ENABLE_JSON define is removed and JSON support is assumed.
  • Action: METAPLAY_ENABLE_JSON definitions should be removed.
• SDK: GameJsonContractResolver is removed. Custom JSON formatters should be registered with the normal [JsonConverter(type-of-converter)] on the target type.
• SDK: On Client, JSON serialization now maps property names into lower camelCase (FooProperty is serialized into fooProperty) to match with server behavior.
  • Action: On client, all uses of JsonSerialization need to be checked for potential regressions.
• SDK: [IncludeOnlyInJsonSerializationMode(JsonSerializationMode.Default)] is no longer included into AdminAPI (Dashboard) json serialization. For these cases JsonSerializationMode.AdminApi should be used instead.
• SDK: PlayerModel.ServerOptions is now MetaplaySDK.Connection.ServerOptions.
• SDK: Google authentication configuration has been changed. EnableGoogleAuthentication is now false by default and IT MUST BE MANUALLY SET TRUE IN PRODUCTION. GooglePlayClientId is not longer defined directly but instead with GooglePlayOAuth2ClientCredentialsPath which is a path or secretsmanager url into a OAuth client configuration JSON exported from Google Cloud Console. Additionally, a new option GooglePlayApplicationId must contain the Google Play Application ID from the Google Play developer console.
• SDK: The MetaDbContext no longer has generics parameters for the persisted player and guild types. The concrete persisted type is automatically discovered from code.
  • Action: Remove generics parameters for MetaDbContext in GameDbContext declarations.
• SDK: Removed integration-side DB initialization in server startup.
  • Action: Remove the InitializeDatabase() function in ServerMain.cs.
• SDK: Platform options is split to GooglePlayStore and AppleStore and the structure has changed:
  • EnableGoogleAuthentication is now ´false` by default and IT MUST BE MANUALLY SET TRUE IN PRODUCTION.
  • GooglePlayClientId is not longer defined directly but instead with GooglePlayOAuth2ClientCredentialsPath which is a path or secretsmanager url into a OAuth client configuration JSON exported from Google Cloud.
  • A new option GooglePlayApplicationId must contain the Google Play Application ID from the Google Play developer console.
  • EnableAppleAuthentication is now ´false` by default and IT MUST BE MANUALLY SET TRUE IN PRODUCTION.
• SDK/Samples: Removed the GAME_SERVER define.
  • Use NETCOREAPP (or one of the UNITY_xxxx_y_OR_NEWER) instead if you want to compile some code in client vs cloud projects (server or botclient).
• SDK: [TypeConverter(typeof(StringIdTypeConverter<T>))] is no longer required or allowed in StringId type definitions, as string conversion is now enabled for all StringId types.
  • Action: Any such attribute annotations should be removed.
• SDK: Added listener method IPlayerModelClientListenerCore.InAppPurchaseValidated which is called when purchase validation completes either with status ValidReceipt or ReceiptAlreadyUsed.
  • Action: If the game implements IPlayerModelClientListenerCore, an implementation for this method needs to be added. The implementation can be empty if the game has no use for it.
• SDK: F64.ToString now uses the normal double formatting, instead of using the n6 format which produces thousand separators (commas).
• SDK: All Config.env.yaml files must parse without errors and warnings.
  • Action: Manually test each YAML with METAPLAY_OPTIONS to validate.
• SDK: If an array is declared in multiple Config.*.yaml or other config sources, the last array definition is now chosen in its entirety. Previously all arrays were merged such that for each declared array element, the last element declaration for the array element index was chosen, and the array length was the maximum of all arrays. The resulting by-index merged array was then concatenated into the property's default value.
  • Action: Avoid array declarations in config.
• SDK: By default, [MetaReservedMembers(...)] now forbids using member tagIds that haven't been reserved. This can be relaxed to the old behavior with [MetaAllowNonReservedMembers].
  • Action: If any violations are detected at SDK init time, either adjust the reserved ranges, add [MetaAllowNonReservedMembers], or remove all [MetaReservedMembers(...)] attributes from the type, as appropriate.
• SDK: InAppPurchaseEvent's methods Clone and CloneForHistory now take a IGameConfigDataResolver parameter, which should be the resolver in the containing PlayerModel.
• SDK: MetaOfferGroupInfoBase and MetaOfferInfoBase now provide convenience constructors for populating data from the corresponding source config item base types. Integrations that customize the source types should now derive from MetaOfferGroupSourceConfigItemBase and MetaOfferSourceConfigItemBase rather than from the "Default" types.
• Server: AdminAPI $type fields in Dashboard no longer carry Assembly information.
  • Action: All hard-coded types of form "Type.Name, Assembly" should be replaced with just "Type.Name".
• Dashboard: $backendApi deprecated -> migrate to gameServerApi module.
• Dashboard: Subscriptions refactored into a module -> refactor imports.
• Dashboard: Game server API, UI components, authentication and permission checker refactored into modules with their own Pinia stores -> refactor imports.
• Dashboard: Event stream refactored into a module -> refactor imports.
• Dashboard: Vue 2.7 upgrade -> this.root was removed and other potential issues in customer code -> test well.
• Dashboard: $backendApi deprecated -> migrate to gameServerApi module.
• Dashboard: Reusable core components refactored into a module -> refactor imports.
• Dashboard: auth-tooltip component renamed to meta-auth-tooltip -> refactor imports.
• Dashboard: Integration API has been rewritten -> refactor uses.
• Dashboard: Project structure has been completely redone and the game-specific code now has its own root project that imports core SDK modules -> migrate existing implementations.
• Dashboard: Node updated to 18.x in anticipation to the next LTS cycle after this release is out -> upgrade local version and CI systems.
• Dashboard: mainStore renamed to coreStore for consistency with the other modules -> refactor imports.
• Dashboard: Local dashboard is now started from <project>/Backend/Dashboard> npm run serve instead of <project>/MetaplaySDK/Backend/Dashboard> npm run serve
• Dashboard: meta-generated-view has been refactored completetly and split into meta-generated-content, meta-generated-card and meta-generated-section. Most related APIs have changed.
• Dashboard: makeVModelForm helper method is no longer available.

Added

• SDK: Offline state persistence now supports schema migrations and atomic file operations to make the feature more robust.
• SDK: Support for nested arrays and/or collections in serialization (eg, int[][] or List<int[]>[]).
• SDK: Game-specific StringId types can derive from StringId<> indirectly. This can be used to make families of StringId types.
• SDK: Json serialization supports serializing tuples as arrays.
• SDK: Added support for Play Games Services v2 Social Authentication.
• SDK: Added new variants of PlayerActorBase and GuildActorBase that default the corresponding persisted type to the SDK type. This allows removing some boilerplate in the common case of not needing to customize the persisted type.
• SDK: EntityAsk handler methods may optionally accept EntityId of the sender entity alongside the message.
• SDK: Allow passing in game-specific context data to the MetaplayerReward.Consume() function for analytics purposes.
• SDK: "Deserialization converter" mechanism to facilitate changing the serialization format of an existing type: for example, changing a concrete class to abstract (and deserializing existing data as a specific child class).
• SDK: Config sheet parsing now supports declaring Experiment Variant overrides in variant override columns in addition to variant rows.
• SDK: GameConfigBuildTemplate now implements overrideable default building of config entries. Sample projects have been updated to use this new API.
• SDK: Added DefaultGameConfigBuild implementation that is used for config building when no integration exists.
• SDK: Player progress is now persisted when running in Offline Mode.
• SDK: Added support for WebSockets in WebGL builds and in the server.
• Dashboard: Added a new MetaClipboardCopy button to overview card to make copying of target ID's easier and more consistent.
• Dashboard: Added a new button on the broadcast overview card, to make it easier to duplicate an exisiting broadcast.
• Dashboard: Added a new link into Database Entity Inspector if Player view data loading fails to make is easier to inspect the broken player state.
• Dashboard: Game-specific code now supports TypeScript.
• Dashboard: Migrated to a new toast notification plugin and added new custom hooks for adding toasts to the dashboard.
• Dashboard: Added support for MetaRefs and StringIds in generated forms. These will show a dropdown list based on the currently active gameConfig.

Changed

• SDK: Upgraded Dockerfiles to .NET 6.0.8 (and SDK 6.0.400).
• SDK: Messages marked as internal (MessageDirection.ClientInternal and ServerInternall) may no longer be in the shared code.
• SDK: Allow specifying Environment:SystemHttpListenHost. Defaults to '127.0.0.1' when running locally (to only allow access from localhost) and '0.0.0.0' in the cloud (to allow Kubernetes to reach it).
• SDK: Player name validation moved from PlayerActorBase.ValidatePlayerName into PlayerRequirementsValidator.
• SDK: In Offline Mode, the player is now persisted on disk by default. You can disable this by setting MetaplayOfflineOptions.PersistState to false in your MetaplayClientOptions.
• SDK: AdminAPI no longer deserializes arbitrary types from JSON objects. Instead, type must be statically defined at deserialization site, or the dynamic type must be [MetaSerializable].
• SDK: Database table mappings for IPersistedItem classes are now automatically discovered from code, removing the need for declaring entries for the mapped classes in MetaDbContext (or GameDbContext for game-specific classes). The old style configuration of DbSet<> fields in the context class has been preserved for backwards compatibility but will likely be deprecated in the future. Any IPersistedItem concrete classes that don't have a corresponding old style DbSet<> entry in the context class need to declare the database table name via a Table attribute.
• SDK: Removed the need of declaring a game-specific GameDatabase class when no custom queries are needed.
• SDK: Removed throttling database queries per MetaDatabase context and instantiating new context objects per use.
• SDK: Introduced SDK-side server projects (Metaplay.Cloud, Metaplay.Server, Metaplay.BotClient) and modified game projects to depend on them rather than importing sources from SDK folders.
• SDK: BotClient main entrypoint moved from BotClientMain (SDK-side) to integration side BotClient.cs.
• SDK: METAPLAY_ENABLE_GUILDS is deprecated. The guilds feature is now always built into the SDK assemblies.
• SDK: OrderedDictionary<> error messages were improved to include the key/value of interest to make debugging easier.
• SDK: PlayerStateRequest/Response has been replaced with generic InternalEntityStateRequest/Response.
• SDK: The initial PlayerModel is no longer logged when starting the client to improve performance. The log lines are commented out in code. In case you want to re-enable them, search for {InitialPlayerModel} in MetaplayClient.cs and DefaultOfflineServer.cs.
• SDK: Server RuntimeOptions (Configs/Config.yaml files) no longer tolerate and ignore unrecognized definitions. Unknown properties or subproperties are now a fatal error. Failing to parse a property value to the target datatype is a fatal error.
• SDK: The server now runs schema migrations on to-be-imported player models before generating the diff view for dashboard.
• SDK: JSON serialization for Game Config contents now shares the serializer with the envelope. This makes the customized serialization style consistent in the whole JSON document.
• SDK: AtomicFileReadWriteUtil has been renamed to AtomicBlobStore and includes a WebGL implementation on top of the browser's localStorage. localStorage is used to allow robust persisting of the player state when the tab/browser is being closed.
• SDK: In WebGL builds, MetaplayCoreOptions.ProjectName is now included in the IndexedDB database name to reduce the chance of conflicts across multiple projects.
• SDK: The check that protocol hashes match on client and server has been temporarily disabled due to the deprecation of the compile-time guilds feature toggle on server side. The check will be re-enabled in Release 21.
• Dashboard: Vite updated to 3.x for faster compilation times.
• Dashboard: Node update to 18.x in anticipation of the next LTS cycle.
• Samples: Idler now uses asynchronous scene loading, managed in ApplicationStateManager.cs.
• Misc: tests.py script argument --backend-dir now defaults to Backend rather than Server, update CI scripts in light of this!

Fixed

• SDK: Switch MetaplaySystemHttpServer to use ASP.NET. This fixes the ArgumentNullExceptions that System.Net.HttpListener can throw if requests are made during initialization.
• SDK: Fixed broken Unity build with certain MetaRef<> patterns.
• SDK: Fix unit tests to run from within the Rider IDE.
• SDK: Google Sheet fetcher error messages are less cryptic and have more relevant error description for the most common error cases.
• SDK: ActiveLogicVersion is now correctly set to the minimum version on server start of the supported range when force-updating from older version.
• SDK: Fixed SpreadsheetContent.FilterColumns throwing IndexOutOfRangeErrors on sparse Spreadsheet data.
• SDK: If a localization sheet contains the same language multiple times, a clear error message reported instead of failing internally to a constraint violation.
• SDK: Indexer properties (object[param1, param2]) no longer break JSON serialization. The properties are automatically ignored and no longer need to be manually marked as Ignored.
• SDK: Limit the number of incident reports being purged at a time to avoid SQL timeouts when a large number of reports have accumulated.
• SDK: Any social login claims made between application start and session start are no longer lost. The claims are buffered and flushed on session start.
• SDK: Fixed a reflection-related failure in Unity game config building, caused by an apparent regression in Unity. The failure was present at least in Unity 2021.3.9f1 and 2021.3.10f1, but not yet in 2021.3.5f1.
• Dashboard: Fixed display of user details when logging in to the Dashboard without any roles assigned.
• Dashboard: Updated the action-delete-player modal, to clearly communicate when a player is scheduled to be deleted.
• Dashboard: Fixed player experiment details to better reflect and communicate the different experiment stages.
• Dashboard: Fixed player save file size to display the correct size.
• Dashboard: Fixed searching audit event logs by username.
• Dashboard: Fixed player's "Remove Authentication Method" dialog not closing after successfully removing the selected method.
• Dashboard: When building a game config, the default sheet id again uses the GoogleSheets:GameConfigSheetId runtime option instead of a hardcoded id mistakenly added in release 19.
• Dashboard: Errors during initialization are now reported with more information in Firefox. Previously Firefox was missing pertinent information that was only shown in Chrome.
• Server: Harmless warnings of long HTTP requests to /sse have been silenced.

Release 20+Web3 (2022-10-03)

Added

• SDK: Added support to log in with ImmutableX account.
• SDK: Basic NFT support, including: modeling NFTs as C# classes, tracking players' NFT ownerships, and publishing NFT metadata to an S3 bucket.