Metaplay Docs

Appearance

Release 26

December 22nd, 2023

Highlights ​

  • Major improvement: .NET 8 support brings many performance improvements and access to the latest improvements of the platform.
    • Action recommended: We strongly recommend upgrading to .NET 8 as official support for .NET 7 will end in May 2024.
  • New preview feature: Multiple client version support allows the server to support multiple client versions at the same time. This allows you to do minor updates to your game client without forcing all players to update at the same time. Ask us for more details if you're interested in using this feature.

Version Compatibility ​

SDK ​

  • This release requires a synchronized upgrade of the client and the server due to backward-incompatible changes in the networking protocol.
    • Action required: Bump your game's MetaplayCoreOptions.supportedLogicVersions to force a synchronized update of your game client and server.
  • This release contains the following DB schema migrations that will be automatically applied on server startup when the updated server is deployed:
    • PublishedAt and UnpublishedAt columns have been added to the Localizations and StaticGameConfigs tables.
    • LogicVersion column has been added to the Players table.

INFO

Note: If you have a service contract signed with Metaplay, your SDK integration has already been updated to reflect any backwards incompatible API changes in the Metaplay SDK in the SDK upgrade pull request of your project. Otherwise, please see the migration guide for a full list of changes, along with the HelloWorld and Idler samples for references on how to apply the changes.

Infrastructure ​

We recommend upgrading to the latest versions of the infrastructure and game server Helm chart:

  • For infrastructure, terraform module infra-modules v0.2.11.
    • Action recommended: Upgrade your self-hosted infrastructure to use the latest version.
  • For deployments, Helm chart metaplay-gameserver v0.5.1.
    • Action recommended: Upgrade your deployments (in Helm values or CI job parameters) to use the latest version.

The minimum required versions are infra-modules v0.2.2 and metaplay-gameserver v0.4.4.

Changes ​

Live-Ops Dashboard ​

  • Added: Added player scanning error counts to the "All Segments" and "Matchmaker Details" views. You will now be warned if player scanning has encountered errors that might affect the accuracy of the results.
  • Added: Localization archives can now be built from dashboard, in a similar fashion than building game configs.
Under the hood
  • Added: a new MInputSingleSelectRadio component. This is a single-select radio button input for number and string values.
  • Added: a new MInputMultiSelectCheckbox component. This is a multi-select checkbox input for number and string values.
  • Added: Added a new MInputSingleFile component. This is a file picker component for individual files.
  • Added: Added a new MInputSingleFileContents component. This is a file picker component for individual files that also reads the contents of the file into a string.
  • Changed: MInputSingleCheckbox has been renamed to MInputCheckbox and MetaInputCheckbox has been removed.
  • Changed: MetaInputNumber has been removed in favour of MInputNumber.
  • Changed: Bootstrap-Vue's form input plugins have been removed in favour of the MInput* components.
  • Changed: Updated the audience targeting form in broadcasts and notifications. If enabled, users are required to specify at least one target segment or player before sending a broadcast/notification.
  • Changed: Updated the MListItem component styles and overall usability. The new look and feel are more consistent with the rest of the dashboard.
  • Changed: Renamed MInputSingleCheckbox to just MInputCheckbox for consistency. This component now also has a smaller size variant.
  • Changed: Removed MetaInputCheckbox in favour of MInputCheckbox.
  • Changed: Added sorting and search cell highlight to LocalizationContentsCard. Improved performance overall.
  • Fixed: Typing in search fields of the audit logs page. Also improved general usability of this page.
  • Fixed: Unresponsive log out button.
  • Fixed: An issue in the import entities form. The import button is now correctly enabled/disabled if you directly paste in a valid/invalid archive.
  • Fixed: Vertical scrolling in the quick links dropdown menu.

SDK ​

  • .NET 8: Add support for .NET 8 LTS. The SDK now supports both net7.0 and net8.0. Support for .NET 7 will be removed when support for it ends, around May 2024.
  • Programmable Localizations build pipeline: The localizations archive build pipeline is now implemented by the SDK class LocalizationsBuild that allows overriding the logic for transforming from data sources to the final localizations data, in a similar fashion that the game config build pipeline customization works.
  • Logic Version changes: We've changed the way the SDK handles Logic versioning. Previously, the server would have a single active logic version, which could be selected from the range of supported versions. Now, the server can use a range of logic versions, while the client can now define only a single logic version. This allows older clients to connect to a newer server as long as the server supports the client's logic version.
  • Private S3 file share: The game server can now be configured to serve files from a prefix within the private blob storage (usually a S3 bucket) through the /file/ path. This can be used to distribute arbitrary files to the game client with developer authentication.
Under the hood
  • Changed: Removed the legacy game config build pipeline METAPLAY_LEGACY_GAMECONFIG_PIPELINE.
  • Changed: StringId.CompareTo has been fixed to use Ordinal string comparison instead of InvariantCulture, because InvariantCulture is inconsistent between server and Unity. This affects the default sorting order of StringId types.
  • Changed: Renamed IGameConfigKey<> to IHasGameConfigKey<> to better reflect its purpose.
  • Changed: Game config source item transform methods now take the build log so that messages can be logged during the transformation.
  • Changed: Removed MultiplayerEntityClientContext._clientStore.
  • Changed: Types GameConfigTypeInfo and GameConfigEntryInfo have been moved outside the GameConfigRepository class so that they can be referred to less verbosely.
  • Changed: Location of Unity client build-time generated files has changed and the new location needs to be git-ignored.
  • Changed: The ability to override game config importing via GameConfigBase.PopulateConfigEntries() has been removed.
  • Changed: Game config entries in custom (non-mpc) formats are no longer supported, and the associated mpcFormat parameter of GameConfigEntryAttribute has been deprecated.
  • Changed: GameConfigImporter.ImportJsonLibrary and IGameConfigBuilder.ParseJsonLibrary have been removed.
  • Changed: Renamed GameConfigBuildIntegration.GetAvailableBuildSources() to GetAvailableGameConfigBuildSources() and added GetAvailableLocalizationsBuildSources().
  • Changed: Renamed GameConfigBuildIntegration.GetDefaultBuildParametersType() to GetDefaultGameConfigBuildParametersType() and added GetDefaultLocalizationsBuildParametersType().
  • Changed: Game config build now reports all invalid MetaRefs (i.e. referring to a non-existent item) within config data, instead of only the first one.
  • Changed: Upgrade backend project dependencies. The more relevant ones are:
  • Changed: GMSBlockStore completion is now pushed to a background thread to keep Java main thread as responsive as possible.
  • Changed: TinyBenchmark now provides much more accurate results and supports benchmarking a group of operations in a single call to get more comparable results in cases where CPU is being throttled.
  • Changed: Integration tests now use an in-memory SQLite database to work around disk-based SQLite's bad performance.
  • Changed: We've introduced a new check during game builds to verify that the current platform is the same as the platform you're building for.
    • This is more likely to be a problem when building from the CI/commandline while using a custom build script.
  • Changed: The CHANGELOG.md file has been removed and the contents migrated to the public release notes documents.
  • Fixed: A schedule-based activable is no longer erroneously reported as being in the review phase in cases where the configured schedule has been changed such that it is in the future.
  • Fixed: Translate path separate character to forward slash when referring to blobs in S3. Previously a Windows server would use a different and unintended S3 blob path from a Linux server due to using OS specific path manipulation with S3 paths.
  • Fixed: The segment size estimates shown in the Live-Ops Dashboard are now more accurate in certain situations involving low-quality estimation runs. The final displayed estimate is calculated based on multiple estimation runs. Previously, it was a simple average over all the runs, and its quality would unnecessarily degrade when individual runs had low volume (due to exceptions occurring in the segment evaluation code). Now, it is a weighted average, giving a correctly lower weight to low-volume runs.
  • Added: On Unity, the ConnectionStates.Connecting in MetaplaySDK.Connection.State has new field Phase, which can be used to display more information of the ongoing connection attempt. In particular, phase DownloadingResources can be used to communicate to user that an ongoing download is in progress.

Documentation ​

  • Release Notes: You are currently reading the first instance of the new release notes format. The notable changes are:
    • The release notes document now also contains all detailed technical descriptions of changes previously hosted in the CHANGELOG.md document in the SDK package. See "under the hood" sections.
    • The new Migration Guide section consolidates the migration steps for updating your Metaplay integration from the previous release.

Samples ​

  • .NET 8: All sample backend C# projects now target net8.0.
Under the hood
  • Idler: Removed usage of [GameConfigSyntaxAdapter] and migrated game config source on Google Sheets to use the new syntax.

Migration Guide ​

INFO

Note: If you have a service contract signed with Metaplay, your SDK integration has already been updated!

Live-Ops Dashboard ​

  • Replace all uses of b-form-* components with MInputText, MInputNumber or other appropriate input components.
  • Replace all uses of MInputSingleCheckbox and MetaInputCheckbox with MInputCheckbox.
  • Replace all uses of MetaInputNumber with MInputNumber. MInputNumber has minor inconsistencies when it comes clamping minimum and maximum values, when combined clearOnZero property. Negative numbers in some cases cannot be inputed through keyboard with "-" character first.

SDK ​

  • The legacy game config build pipeline METAPLAY_LEGACY_GAMECONFIG_PIPELINE has been removed. If you are currently using it you'll need to switch to the new config pipeline before upgrading to Metaplay R26.
  • The default sorting order of StringId types has been changed. If you require the sorting of StringIds to remain the same as before, you now need to use an explicit custom comparer that performs InvariantCulture comparison.
  • Replace any usage of IGameConfigKey<T> with IHasGameConfigKey<T>.
  • Update your game config source item transform methods to accept the GameConfigBuildLog parameter: void ToConfigData(GameConfigBuildLog buildLog). For better error reporting during the game config build, use the passed in log instead of throwing exceptions in the transform method.
  • ConfigParserException has been removed, and now the intended way to report config build errors is via GameConfigBuildLog.
    • At simplest, just call buildLog.Error("Some error message") to produce an error which will prevent the config build from completing successfully.
    • You can optionally specify the error context with methods WithLocation and WithVariantId, such as buildLog.WithLocation(item.SourceLocation).WithVariantId(item.VariantIdMaybe).Error("some error") where item is a VariantConfigItem<>, or with method WithSource(GameConfigSourceInfo) where the error concerns the whole sheet (or other source) instead of a specific item.
    • The GameConfigBuildLog is available in IGameConfigBuilder.BuildLog. IGameConfigBuilder is the type of the shared and server parameters to GameConfigBuildTemplate<...>.Build, as well as of the first parameter to the build function returned by GameConfigBuildTemplate<...>.GetEntryBuilder.
  • In classes deriving from MultiplayerEntityClientContext replace all uses of _clientStore with Services.ClientStore.
  • Update any usage of GameConfigRepository.GameConfigTypeInfo to GameConfigTypeInfo, and GameConfigRepository.GameConfigEntryInfo to GameConfigEntryInfo.
  • If your game config integration has a custom implementation of GameConfigBase.PopulateConfigEntries() for assigning game config entries to their respective fields:
    • Remove the custom implementation and review that the SDK import produces an identical result.
    • Migrate any derived game config data generation into GameConfigBase.OnLoaded().
    • Migrate any custom data types previously exported into the config archive to do the transformation as part of the game config build.
  • Ensure that -buildTarget is passed to Unity with the correct platform when building from the CI/commandline.
  • MetaplayCoreOptions has a new property ClientLogicVersion. This should be set to the same value as SupportedLogicVersions.MaxVersion, and updated whenever the supported versions are bumped.
  • PlayerActor._logicVersion has been removed. The player actor now has ClientLogicVersion and ServerLogicVersion properties instead. The client logic version should be used for any logic that should mirror the client, and the server logic version should be used for any communication with other actors on the server.
  • The GameConfigBuildIntegration API has been updated to also support localizations builds and some overrideable API methods have been renamed to reflect this:
    • GetAvailableBuildSources() for enumerating the source for the game config build was renamed to GetAvailableGameConfigBuildSources().
    • GetDefaultBuildParametersType() for explicitly declaring the type of the game config build parameters class was renamed to GetDefaultGameConfigBuildParametersType().

Misc ​

  • Add the new Unity client build temporary folders /Assets/MetaplayGenerated_DONOTSAVE and /Assets/MetaplayGenerated_DONOTSAVE.meta to the .gitignore (or equivalent) file.

Known Issues ​

Live-Ops Dashboard ​

  • The attachment picker in the Send Mail player action can sometimes show incorrectly or duplicate named options in the drop-down list. This is caused by an underlying issue with the MetaInputSelect component when it is used in generated forms. Once a value has been selected, the correct value is always shown. This will be fixed in the next release when we migrate to a new component.

Hotfix Releases ​

Release 26.1 ​

Released on: February 9th, 2024

  • SDK: Added Issuer option to Admin API JWT authentication configuration for the ability to specify issues in token from the environment.
  • SDK: Fixed release package to have the .version file in MetaplaySDK/.version and not in the package root.
  • Unity: Add support for copy-pasting game server endpoint configuration from Metaplay developer portal into client environment config.
  • Leagues: Fixed an issue in the Leagues system where divisions could end up broken during initialization due to messages arriving in an unexpected order. Divisions are now correctly initialized before assigning players to them, and players assigned to uninitialized divisions for any reason are now automatically unassigned.
  • Dashboard: Fixed an issue in the generated form's multi-select component ensuring that users are no longer able to de-select options.