Highlights

LiveOps Dashboard Timeline Improvements

The LiveOps Dashboard timeline view now includes Experiments and Broadcasts. This provides a comprehensive overview of your game's live operations, allowing you to visualize and manage these activities alongside other timeline events.

The timeline is now zoomable, allowing you to smoothly transition from looking at the big picture to looking at a single day, and back again.

Events that are scheduled for "player local" time now indicate the full range of times that they could be active using a ghosted outline. This takes into account the time zones that your players could be playing in.

The timeline has also undergone a series of improvements to its visual styling, UX and performance. Not only does it now look and feel better, but it also runs smoother!

Major Improvement: Metaplay SDK Initialization Performance

The time it takes a player from starting the application to being able to play the game continues to be the focus of our SDK optimization work. In Metaplay R35, we're now wrapping up the effort of porting initialization of SDK registries to use Roslyn source generators in place of reflection. This means that there is no remaining reflection type scanning during the SDK initialization in client, reducing the cost of the call to MetaplaySDK.InitializeForClient() further.

Major Improvement: Game Config Loading Performance

Another bottleneck in the overall load time on client has been the loading and transforming of game config data to memory. We have received reports from projects with large and complex game config payloads seeing game config load times of multiple seconds on lower end devices, even when the current config archive is successfully read from the local filesystem cache. Metaplay R35 brings a number of micro-optimizations to the CPU cost of loading config data and resolving the intra-config dependencies. In our benchmarks, these optimizations were measured to provide an improvement of up to 50% to the overall game config load time. A large part of the optimization work involves reducing the complexity of the generic types involved in the game config system, and these optimizations will provide benefits to the initialization time of the application also outside of game config loading!

Changes

Metaplay SDK

• In-app Purchase History: The full listing of all IAP events is no longer shared with the client. This reduces the player model size sent over network and in client memory for players with large amounts of transactions. For IAP history needs in shared code, such as player segmentation conditions involving purchases, the SDK now exposes a summary of the IAP history as IPlayerModel.InAppPurchaseHistorySummary.
• Storage of Deleted Players: A deleted player is no longer stored as a dummy PlayerModel in the database, but instead has no PlayerModel at all (the Payload column is null). This uses less space in the database and allows deleted players to be efficiently ignored by database scan jobs. See The Lifecycle of a Player for more information. To get the benefits of this change for your pre-existing data, run a one-time Entity Refresher Job for players in each environment at a convenient time after upgrading to this SDK version. However, the system will continue to work normally even if you don't.
• SDK Generic Type Simplification: A number of SDK generic types, such as MetaDictionary and GameConfigLibrary, have been refactored to declare fewer generic methods and generic type dependencies. This is especially important with the IL2CPP runtime where type initialization of generic type specializations is expensive and can result in slow game load times.

Complete List

• Added: EntityAskAsync() now optionally accepts the timeout for the request.
• Added: EntityAsk object now has a convenience EntityAsk.Reply() and EntityAsk.Refuse() methods.
• Added: Entity actor constructors now support dependency injection of metaplay services.
• Added: Support for IReadOnlyList<>, IReadOnlyCollection<> and ArraySegment<> in serialization.
• Added: Prometheus metric game_player_incident_reports_by_country that counts incident reports per player country. See Implementing Player IP Geolocation for how to enable the country information.

• Changed: Updated gameserver C# dependencies.
• Changed: Runtime option PushNotification.UseLegacyApi has been removed as the legacy API has been deprecated by Firebase.
• Changed: Runtime option Database.EnableMySqlLogging has been removed as MySQL logging has been enabled by default.
• Changed: Pooled MySQL connections now have a limited lifetime, even if they've been recently used. This reduces the database instance's memory usage in some high-traffic scenarios.
• Changed: When an entity's schema version has fallen behind the oldest supported specified in [SupportedSchemaVersions(min, max)] and therefore cannot be migrated, the entity will now fail to start instead of being automatically reset. This gives a chance to reinstate the old schema version in the C# code in case it was removed by mistake. Players can still be manually reset via the LiveOps Dashboard.
• Changed: Empty MetaDictionary and GameConfigLibrary key and value collections can no longer be accidentally created via collection expression conversion, to match System.Collections.Generic.Dictionary behaviour.
• Changed: EntityAsk and EntityAsk<T> context parameters in ask handler methods has been moved from Metaplay.Cloud.Sharding.EntityShard into Metaplay.Cloud.Entity.
• Changed: Remove the 500ms sleep when the server is force-terminated due to an unrecoverable error. The delay is no longer needed as logging writes to stdout directly, instead of going via Akka messages.
• Changed: Updated entrypoint binary to use Go v1.25.4.
• Changed: Optimize serialization of long strings to not require a temporary allocation.
• Changed: Failure to deserialize a pending server action is no longer fatal for PlayerActor. An error will be logged, similarly to the action throwing an unhandled exception.
• Changed: Custom database scan job managers are now automatically detected and can be defined without modifying the SDK code.
• Changed: Remove JournalModelRerunChecker consistency check that ensured actions were deterministic on client. The check was expensive in both CPU and memory use. Determinism is already validated by the server-side checksum checks, resulting the same test coverage with a lower cost.
• Changed: MetaMessageRepository no longer uses reflection for initialization and now uses source generation to create the relevant data.
• Changed: AnalyticsEventRegistry no longer uses reflection for initialization and now uses source generation to create the relevant data.
• Changed: Entity actor base constructors that take in EntityId have been deprecated. Actors should now use the default base constructor.
• Changed: The Multiplayer entity actor constructors (MultiplayerEntityActorBase, PersistedMultiplayerEntityActorBase, EphemeralMultiplayerEntityActorBase) accepting logChannelName have been deprecated. Log channel name should be given with a LogChannelName virtual property.
• Changed: Silenced server log messages of undelivered messages during server shutdown.
• Changed: BigQuery analytics sink now uses the Storage Write API instead of the older insertAll streaming API by default. Support for Storage Write API was added in Release 31. The older API is still available for use by setting the AnalyticsSinkBigQuery.UseV2 server option to false.
• Changed: A deleted player is no longer stored as a dummy PlayerModel in the database. Instead, it has no PlayerModel at all (the Payload column is null) and its deletion state is stored in dedicated columns.
• Changed: DynamicEnum-deriving types property AllValues and methods FromId() and FromName() can no longer be used before the Metaplay SDK core has been initialized; an exception will be thrown. Previously, they were not explicitly forbidden but had ill-defined behavior if used before at least AssemblyUtil.LoadLocalAssemblies() had been called.
• Changed: DynamicEnum static members with [IgnoreDataMember] are now ignored.
• Changed: Scan jobs now skip entities with null Payload by default. This includes uninitialized and deleted players (except for pre-existing deleted players that have not yet been migrated to the new null-Payload form).
• Changed: Entities in a crash loop are now throttled to prevent excessive logging and cpu use.
• Changed: Removed periodic checking of the player model clock being in accepted bounds when there is no client connected. This eliminates spurious "client too far behind" warnings in the server log.
• Changed: Google Play IAP receipts that fail signature validation are now printed in logs (base64 encoded) to help debugging client IAP configuration issues.
• Changed: The type of MetaSerializableType.Members has been changed from List<MetaSerializableMember> into MetaSerializableMember[].
• Changed: The type of ClientLoggingConfig.LogLevelOverrides has been changed from List<LogLevelOverrideSpec> into LogLevelOverrideSpec[].
• Changed: The type of ConnectionEndpointConfig.BackupGateways has been changed from List<ServerGatewaySpec> into ServerGatewaySpec[].
• Changed: If actor has shut down, EntityAskAsync() will now fail with a EntityUnreachableError{ ErrorCause = SenderActorIsAlreadyDead } instead of waiting for the timeout.
• Changed: Refactored the StringId implementation for better performance, in particular the Add() path.
• Changed: Simplified MetaDictionary to depend on fewer types on static type initialization, to reduce per-specialization initialization time.
• Changed: Refactored GameConfigLibrary to be an abstract base class, the actual storage of library items is left for the concrete implementation class. This allows separating the more complex deduplicating implementation used on server into its own class never accessed by the client, and additionally using MetaDictionary<object, IGameConfigData> as storage when the key type is not a value type.
• Changed: SDK-side validation of MetaOffers and MetaOfferGroups now happens during config build, rather than on load.
• Changed: Disabled null checks and array bounds validation in IL2CPP builds of the generated serializer, as the generated code handles these checks itself.
• Changed: Eliminated use of reflection in MetaRef resolving.

• Fixed: Dashboard build and unit test stages in the server Docker image build are now forced to run on host architecture. Most notably, this speeds up image builds and integration test runs on non-X86 machines such as newer Mac computers.
• Fixed: Fixed potential checksum mismatch with Guild Transactions due to divergence in PlayerPlan computation.
• Fixed: Database connection pool size now accounts for having multiple shards on a single DB instance.
• Fixed: On WebGL, fixed a warning message in Browser Console about a missing onProgress handler.
• Fixed: Fixed compatibility issue with Newtonsoft.Json-for-Unity.Converters that caused MetaplaySDK fail initialization.
• Fixed: Fixed a bug where JournalModelChecksumChecker could cause timeline state to be mutated, resulting in potentially different error behaviour being observed when running with and without journal checkers enabled.
• Fixed: Server build no longer requires Secrets folder to exist.
• Fixed: Fixed issue with leagues and player deletion where the player would try to leave a None division when deleted.
• Fixed: Fixed one unnecessary resource correction roundtrip in session start.
• Fixed: Fixed missing InnerException message in server logs for Entity crash stack traces.
• Fixed: When time skip has been applied, the duration shown in the "Server is now ready to serve, {StartElapsed}ms elapsed since process start!" log message after server start is no longer off by the time skip's amount.
• Fixed: When the player actor fails to generate a presigned S3 URL for an incident report upload (for example due to an AWS failure), it falls back to requesting the incident report via the normal game connection. Previously, the actor would crash in this case, causing the game session to be terminated.
• Fixed: Fixed a rare race on server where a single node of a cluster could fail on startup with EntityUnreachableError error.
• Fixed: Fixed an assembly loading bug that caused some projects' EF database migrations to erroneously remove (or not initially add) some database tables.
• Fixed: Fixed unsupported type ClientLaunchStatistics error while using Firebase Analytics.
• Fixed: Improved performance and reduced memory usage of game config diffing.
• Fixed: Fixed showing both the environment config error dialog and the SDK init error dialog, when entering playmode in Unity Editor with failed SDK init.
• Fixed: Fixed potential client deadlock if Latency Simulation was used, or in Editor where message transport Fault Injection is enabled.
• Fixed: Fixed a client-side error preventing in-app purchases on purchasing platforms implemented as a custom ClientDrivenIAPClientDelegate implementation.
• Fixed: Using social platform authentication (Google Play, Facebook, etc) to reassociate the client device with a player account no longer produces an incident report. It used to erroneously produce a TerminalNetworkError with subtype SocialAuthenticateForceReconnectConnectionError.
• Fixed: Fixed serializer compilation failure if MetaSerializable objects were defined in the predefined Unity assemblies.
• Fixed: If the cluster leader node (service node) is lost and restarted, dynamically scaling nodes now stay in the cluster, instead of leaving and immediately rejoining.
• Fixed: Fixed case where TaskQueueExecutor created for a ThreadPool scheduler could inherit Synchronization Context from Unity's main thread if enqueued task was inlined.

LiveOps Dashboard

• Guild Export: The Guild Details page now includes a new "Export Guild" action that allows you to export a guild and all its members as an entity archive.

• Game Server Metrics: Game Server Metrics chart components have been improved, giving a sleek new look and improved performance to the graphs.

Complete List

• Added: A copy-to-clipboard button next to transaction IDs in the Player Purchase History card to make sharing easier.
• Added: A timestamp tooltip to event logs cards (i.e. Player Events and Server Errors cards).
• Added: Experiments are now shown on the timeline.
• Added: Broadcasts are now shown on the timeline.
• Added: A new prop overflowCard has been added to MCard that controls whether slot content can overflow the card's boundaries. For example, use to allow tooltips to overflow the card.
• Added: A new "Export Guild" admin action on the Guild Details page to export guild data.
• Added: A new test fixture freshTestGuild for performing end-to-end tests with Guilds.

• Changed: The DailyCohortsChart and CohortsChart components have been deprecated in favor of the new chart components. If you had direct custom use of the old chart components, contact us for migration assistance!
• Changed: Removed the default variant from all input components to keep the types consistent. Simply leave the field undefined for default styling.
• Changed: Shortened the length of transaction IDs shown in the Player Purchase History card.
• Changed: Relative time formatting in MDateTime component now shows "a few seconds ago" for times under 1 second.
• Changed: MDateTime tooltips no longer show milliseconds for improved readability.
• Changed: Updated @fontawesome to v3.1.2, which increased default icon sizes and padding, and may slightly affect layout and spacing across the dashboard.
• Changed: Improved landing page for new users or users without roles, including adding a human readable resolution step.
• Changed: Changed API endpoint GET /api/gameConfig/{id}?binary=true into GET /api/gameConfig/{id}/download
• Changed: On the database scan jobs page, the collapsible information in the lists has been improved. The information is now consistent across the different lists and clearly tells you if a job failed due to unrecoverable errors.
• Changed: Duration utility functions have been moved from @metaplay/meta-ui-next to @metaplay/meta-utilities package for better separation of concerns.

• Fixed: On the timeline view, league seasons no longer abruptly disappear when scrolling too far into the future.
• Fixed: On the timeline view, past and current league seasons are no longer erroneously shrunk towards the right by the amount of the preview duration.
• Fixed: "View" buttons in the timeline inspector for activables no longer sometimes lead to a 404 page.
• Fixed: Broadcast audit logs now correctly show the individual broadcast's audit logs instead of all broadcasts audit logs.
• Fixed: The MInputSelectDropdown component now maintains proper width and layout on smaller screens.
• Fixed: Fixed an invalid duration that appeared on the GameServerMessageCenterView.
• Fixed: The MInputNumber component no longer triggers a validation error when you clear a field that has allow-undefined enabled and a min and/or max value defined.
• Fixed: The MInputNumber component clear button no longer disappears when you enter value 0 for a field that has the allow-undefined enabled.
• Fixed: Enabling the end time in the Experiment form now sets it to start time + 1 day by default.

Documentation

• Added: Guidance on filtering Analytics Events in the Dashboard Event Log views based on keywords: Implementing Analytics Events in Game Logic.

Known Issues

We are aware of the following issues in this release:

Incorrect Exception Type in FileUtil.ReadAllBytesAsync on Android

FileUtil.ReadAllBytesAsync() is documented to throw IOException if the target file does not exist. When accessing Android assets filesystem (i.e. files included in the APK itself), FileUtil.ReadAllBytesAsync() may throw NullReferenceException instead.

Migration Guide for All Customers

Please apply the following changes to your project to ensure compatibility with the latest Metaplay SDK.

Backward-Incompatible Changes

Bump your game's MetaplayCoreOptions.supportedLogicVersions to force a synchronized update of your game client and server.

Migration Guide for Self-Service Customers

Premium SDK Update Support

If your support contract includes Metaplay-provided SDK updates, all the following steps have already been applied to your project. You can skip this migration guide!

This guide offers step-by-step instructions for migrating your project to the latest version of the Metaplay SDK. You can skip the migrations steps for features you are not using in your project.

Before You Begin

It's a good idea to run the Metaplay integration test suite on your project before and after upgrading to the latest SDK version.

MyProject$ metaplay test integration

You should get a clean test run before starting the upgrade process to know that your project is in a good state, and know that any test failures after the upgrade are related to the upgrade itself.

For All Metaplay Projects

The following core SDK changes affect all Metaplay projects:

Apply Database Schema Migrations

Metaplay's built-in database schema has changed, and you need to apply the migration steps to your project.

Migration Steps:

1. Generate the database schema migration code with:

   # Install or update the EFCore tool:
   Backend/Server$ dotnet tool install -g dotnet-ef --version 9.0.11
   # Then, generate the migration code:
   Backend/Server$ dotnet ef migrations add MetaplayRelease35

2. Then, add the generated files to your project's source control. For example, using Git:

   Backend/Server$ git add .
   Backend/Server$ git commit -m "Database schema migrations"

The migration steps will be automatically applied when you deploy the updated game server into an environment.

Update NUnit to v4.4.0

We have updated the NUnit version used for the MetaplaySDK backend unit test projects, if you run Metaplay's Unit tests as part of your own tests. We recommend updating to v4.4.0 as well to prevent issues due to mismatching versions.

For more information on the migration, see NUnit 4.0 Migration Guidance. Note that to use the automatic Roslyn CodeFixes, you might have to update to NUnit 4 before starting the MetaplaySDK update.

For Games With Customized LiveOps Dashboard

The following LiveOps Dashboard changes affect projects that have a game-specific dashboard project:

Update the LiveOps Dashboard Project Files

As usual, we have updated the underlying dependencies and configurations of the LiveOps Dashboard. This causes changes to several configuration files, which you will need to update in your dashboard project. We use the MetaplaySDK/Frontend/DefaultDashboard folder as the source of truth for these files.

Migration Steps:

1. Update the package.json to update your project's dependencies.

   • If you have custom dependencies, manually update them or use a file comparison tool to merge the changes.
   • If not, copy and overwrite the package.json file directly from the MetaplaySDK/Frontend/DefaultDashboard directory. Next, restore the name property inside the file to that of your project. This is typically of the form "name": "<projectName>-dashboard".

2. Copy and overwrite the following files:

   • tsconfig.json
   • tsconfig.node.json

Clear and Recreate the Dashboard Dependencies

To ensure that your dashboard project has the correct dependencies, you will need to clear the existing cached files and recreate them.

You should ensure that you have Node version 22.14.0 (the latest 22.x version at the time of writing) installed. To check the current version, run node --version. If you are using nvm, you can update Node with:

# Install Node 22.14.0 with Node Version Manager (nvm).
nvm install 22.14.0

# Use the new version.
nvm use 22.14.0

Migration Steps:

1. Next, remove any files that Node has cached in your repository. This will lead to a fresh install of all dependencies.
   • Run git clean -fdx ':(glob)**/node_modules/*' from the root of your repository. This clears any currently installed dependencies.
   • Run git clean -fdx ':(glob)**/dist/*' from the root of your repository. This clears any previously built files.
   • Delete the pnpm-lock.yaml file from the root of your repository. This clears the cached dependency versions.
2. Run pnpm install in your 'Dashboard' folder. This recreates all of the above files and folders with the correct dependencies.

Remove Any Uses of 'default' Variant

Our input components no longer have the 'default' variant. Simply leave the field undefined for default styling or use 'primary' if you want to be more explicit.

Migration Steps:

1. Run a type-check on your dashboard project to find any uses of the 'default' variant in your code

   # Run from anywhere inside your project directory structure
   metaplay build dashboard

2. Replace the 'default' variant with undefined or 'primary' in the relevant places.

   For example:

   MInputText(
   :model-value="someValue"
   @update:model-value="(newValue) => someValue = newValue"
   :variant="someValue === '' ? 'danger' : 'default'"
   :variant="someValue === '' ? 'danger' : undefined"
   )

   or

   MInputTextArea(
   :model-value="someValue"
   @update:model-value="(newValue) => someValue = newValue"
   :variant="someValue === '' ? 'danger' : 'default'"
   :variant="someValue === '' ? 'danger' : 'primary'"
   )

Adjust FontAwesome Icons

As part of the FontAwesome dependency update, icon sizes and padding have changed. Review your custom dashboard components and, if necessary, adjust icon sizes or spacing as follows:

Migration Steps:

1. Review your dashboard for any custom FontAwesome icon usage.

2. Adjust icon sizes or padding/margins as needed. For example, if you previously used size="sm", you might change it to size="xs", and/or remove any custom padding/margin that is no longer necessary.

   fa-icon(
       icon="wrench"
       size="sm"
       size="xs" // Adjust size as needed (e.g., 'xs' instead of 'sm'
       class="tw-px-2" // Remove/reduce custom padding/margin if it is not needed anymore.
       )

Update Duration Utility Function Imports

The duration utility functions have been moved from @metaplay/meta-ui-next to @metaplay/meta-utilities package.

Migration Steps:

1. Search your dashboard project for any imports of duration utility functions from @metaplay/meta-ui-next.

   import { parseDotnetTimeSpanToLuxon } from '@metaplay/meta-ui-next'

2. Update the import statements to use @metaplay/meta-utilities instead.

   import { parseDotnetTimeSpanToLuxon } from '@metaplay/meta-utilities'

Update TypeScript Typing for Indexed Access

Vue has updated the default TSConfig to match closer the Microsoft's default TSConfig. This includes enabling noUncheckedIndexedAccess flag.

To ensure indexed access result in the correct type, you need to ensure stricter typing or add null assertions. Or alternatively you can disable the noUncheckedIndexedAccess flag.

Migration Steps:

1. Either update typing to ensure indexed elements exist:

   const myArray: string[] = [ "1", "2" ] 
   const myArray: [string, ...string[]] = [ "1", "2" ] 
   const firstField: string = myArray[0]

2. Or add not-null-assertion on accesses when the element is known or checked to exist:

   const myArray: string[] = [ "1", "2" ]
   if (myArray.length > 0) {
       const firstField: string = myArray[0] 
       const firstField: string = myArray[0]!
   }

3. Or use ? or ?? operators to handle possibility of the missing element:

   const myNumber = 3
   const numberToFriendlyString: Record<number, string> = { 0: "none", 1: "just one", 2: "pair"}
   const friendlyName: string = numberToFriendlyString[myNumber] 
   const friendlyName: string = numberToFriendlyString[myNumber] ?? "some"

4. If the above apporaches are not suitable, index access type checking can be disabled with:

   Backend/Dashboard/tsconfig.app.json

   {
       ...
       "compilerOptions": {
           ...
           "noUncheckedIndexedAccess": false, 

For Games Using In-App Purchase History on Client

The change of turning the full in-app purchase history server-only means that any existing use of it on client (or shared game logic) will no longer work. The most common shared use of this data is for player segmentation conditions, as the segment conditions need to be evaluatable both on server and client. For example, a segment condition for the number of lifetime purchases a player has made could previously simply count the entries in PlayerModelBase.InAppPurchaseHistory.

For continuing to be able to implement purchase-related logic in shared code, the SDK will now generate and maintain a "summary" of the purchase history as member PlayerModelBase.InAppPurchaseHistorySummary. This data is never persisted to database, but rather created whenever the model is loaded and then updated in response to changes in the full purchase history.

Migration Steps:

1. Review existing uses of PlayerModelBase.InAppPurchaseHistory. In R35, a member by that name no longer exists so all legacy access will generate compile errors that need to be addressed.
2. For uses in server-only code, update the reference to refer to PlayerModelBase.FullInAppPurchaseHistory instead. The data contained in the full history has not changed, so no further action should be required.
3. Check if the data that you are currently retrieving from the purchase history is readily available in the purchase summary, PlayerModelBase.InAppPurchaseHistorySummary. The SDK provides a number of common aggregations over the full history of events, as well as price data for purchases within the last 30 days that can be used for aggregations involving recent player behavior.
4. If the data that you require is not directly provided by the SDK default summary, introduce a customized summary class for exposing the required data to the client.
   • Add a class deriving from InAppPurchaseHistory into the project, add serializable members for your custom aggregations and populate them in the constructor.
   • Override PlayerModelBase.CreateInAppPurchaseHistorySummary() to create your custom summary class.

For Games With Custom Database Scan Jobs

The interfaces for defining new database scan jobs have been adjusted to avoid needing custom modifications to the SDK code. These migrations only apply to you if you have already defined custom scan jobs.

Update Job Priority Numbers

The SDK's scan job priority numbers in DatabaseScanJobPriorities have been updated to set them further apart from each other, allowing for more granularity in your custom priority numbers between the SDK's priorities.

If you have defined custom priority numbers for the Priority property in your DatabaseScanJobSpec subclasses, you should update them accordingly.

The SDK's DatabaseScanJobPriorities have been changed as follows:

• ScheduledPlayerDeletion: 0 -> 100
• EntitySchemaMigrator: 1 -> 200
• EntityRefresher: 1 -> 200
• NotificationCampaign: 2 -> 300

Migration Steps:

1. In each of your classes derived from DatabaseScanJobSpec (including from the MaintenanceJobSpec intermediate class), update the Priority number if needed.

   a. If reusing an SDK-defined constant from DatabaseScanJobPriorities: no change needed.

   MyCustomScanJob.cs

   // OK, will keep working as before.
   public override int Priority => DatabaseScanJobPriorities.ScheduledPlayerDeletion;

   b. If using some other number: consider if the number needs to be updated. To keep the correct priority relative to the SDK-defined jobs, see the list above.

   MyCustomScanJob.cs

   // Intends to be within the SDK's priority range.
   public override int Priority => 1; 
   public override int Priority => 200; 
   // Or alternatively: can now fit numbers strictly between SDK's priority numbers.
   public override int Priority => 250; 
   
   // Intends to be higher than all other jobs.
   public override int Priority => 3; 
   public override int Priority => 10000; 

Update Custom DatabaseScanJobManager Integration

This only applies to you if you have defined custom subclasses of DatabaseScanJobManager. Custom database scan job managers are now detected and instantiated automatically and no longer need modifications to the SDK-side file DatabaseScanCoordinator.cs.

Note that custom jobs using the MaintenanceJobSpec base class are not affected, because they use an SDK-defined manager class.

Migration Steps:

1. Add the [MetaSerializableDerived(TYPE_CODE)] attribute to your manager class. TYPE_CODE must be the same number as the corresponding enum value in LegacyDatabaseScanJobManagerKind.

   MyCustomScanJob.cs

   [MetaSerializable] 
   [MetaSerializableDerived(1000)] 
   public class MyCustomScanJobManager
   {
   }

2. Remove the custom enum value from the SDK-side LegacyDatabaseScanJobManagerKind.

   MetaplaySDK/Backend/Server/DatabaseScan/DatabaseScanCoordinator.cs

   public enum LegacyDatabaseScanJobManagerKind
   {
       ...
   
       MyCustomScanJobManager = 1000, 
   }

3. Remove the custom code from the SDK-side GetJobManagerOfKind(). This method has been removed entirely.

   MetaplaySDK/Backend/Server/DatabaseScan/DatabaseScanCoordinator.cs

   DatabaseScanJobManager GetJobManagerOfKind(DatabaseScanJobManagerKind kind) 
   { 
       switch (kind) 
       { 
           ... 
           case DatabaseScanJobManagerKind.MyCustomScanJobManager: return _state.MyCustomScanJobManager; 
           ... 
       } 
   } 

4. The custom member in DatabaseScanCoordinatorState will be automatically migrated and set to null when the server starts. Therefore, you should not remove this member immediately, but can do so after the server has been successfully running in all important environments (especially production).

   MetaplaySDK/Backend/Server/DatabaseScan/DatabaseScanCoordinator.cs

   public class DatabaseScanCoordinatorState : ISchemaMigratable
   {
       ...
       [MetaMember(1000)] public MyCustomScanJobManager MyCustomScanJobManager { get; private set; } = new MyCustomScanJobManager(); 
       // TODO: Legacy member. This can removed after this version of the code has been successfully running in production.
       [MetaMember(1000)] public MyCustomScanJobManager Legacy_MyCustomScanJobManager { get; private set; } = new MyCustomScanJobManager(); 
   }

Account for Skipping of Null-Payload Entities

Starting with this release, database scan jobs now skip entities with null Payload by default. This includes players in an uninitialized state (a usually short-lived state during a new player account creation) as well as deleted players (except for pre-existing deleted players that have not yet been migrated to the new null-Payload form introduced in this release).

Skipping null Payloads is almost always what you want in scan jobs. If this is the case for you, there is no change needed, except for a possible code simplification. If you do not want to skip null Payloads, a simple override is needed in your scan job.

Migration Steps:

1. Find all of your custom implementations of the DatabaseScanProcessor base class. Note that the SDK also has implementations of this class, but you can ignore those.

   MyCustomScanJob.cs

   public class MyCustomScanJobProcessor : DatabaseScanProcessor<...>
   {
       ...
   }

2. Inspect the StartProcessItemBatchAsync(...) method and understand what it does with items that have null Payload.

3. If it doesn't do anything important, such as only perhaps records some statistics and skips the item, you can simply remove the code specific to null Payload, because such items are now skipped by default:

   MyCustomScanJob.cs

   public class MyCustomScanJobProcessor : DatabaseScanProcessor<SomeItemType>
   {
       ...
   
       public override Task StartProcessItemBatchAsync(IContext context, IEnumerable<SomeItemType> items)
       {
           foreach (SomeItemType item in items)
           {
               if (item.Payload == null) 
                   continue; 
   
               ...
           }
       }
   }

4. However, if null-Payload items are actually important and should be processed, then override the ItemFilter property to return DatabaseItemSpec.ItemFilter.IncludeAllItems:

   MyCustomScanJob.cs

   public class MyCustomScanJobProcessor : DatabaseScanProcessor<SomeItemType>
   {
       ...
   
       public override DatabaseItemSpec.ItemFilter ItemFilter => DatabaseItemSpec.ItemFilter.IncludeAllItems; 
   }

Miscellaneous API Changes

These changes affect you in case you happen to use any of the APIs changed. You can build your project to get a list of any incompatibilities instead of going through the list one item at a time.

Remove Obsolete Runtime Options

The following runtime options have been removed:

• PushNotifications.UseLegacyApi - The underlying API has been deprecated.
• Database.EnableMySqlLogging - MySql logging is now enabled by default.

Migration Steps:

1. Remove unused runtime options

   Backend/Server/Config/Options.*.yaml

   PushNotifications: 
       UseLegacyApi: true
   Database: 
       EnableMySqlLogging: true

Update References to EntityAsk and EntityAsk<T> Types.

To make discovery of the types easier, EntityAsk and EntityAsk<T> have been moved from being in nested class Metaplay.Cloud.Sharding.EntityShard into the Metaplay.Cloud.Entity namespace.

Migration Steps:

1. Update references EntityShard.EntityAsk and EntityShard.EntityAsk<T> in Entity ask handlers into EntityAsk and EntityAsk<T>

   using Metaplay.Cloud.Entity; 
   
   ...
   
   [EntityAskHandler]
   public void HandleExample(EntityShard.EntityAsk<ExampleResponse> entityAsk, ExampleRequest request) 
   public void HandleExample(EntityAsk<ExampleResponse> entityAsk, ExampleRequest request) 
   {
   }

Update Entity Actor Constructors

Base classes for Entity Actor no longer take constructor parameters. This removes the need for dummy forwarding constructors when creating an Entity Actor.

Entity actor constructors accepting EntityId parameter have been deprecated. The EntityActor now automatically discovers the EntityId. Additionally, multiplayer entity actor constructors for setting logChannelName is deprecated. Log channel name should be given with a LogChannelName virtual property.

Migration Steps:

1. For all Entity Actors, remove dummy forwarding constructors

   MyActor.cs

   class MyActor
   {
       ...
       public MyActor(EntityId entityId) : base(entityId) {} 
   }

2. For all Entity Actors with a costructor, remove EntityId entityId constructor parameter. Replace uses of entityId with _entityId.

   MyActor.cs

   class MyActor
   {
       ...
       public MyActor(EntityId entityId) : base(entityId)
       public MyActor()
       {
           DoSomethingWithId(entityId) 
           DoSomethingWithId(_entityId) 
       }
   }

3. For all Multiplayer Entity Actors that pass logChannelName parameter, set the name using LogChannelName virtual property.

   MyActor.cs

   class MyActor
   {
       protected override string LogChannelName => "foo"; 
       ...
       public MyActor(EntityId entityId) : base(entityId, logChannelName: "foo")
       public MyActor()
       {
       }
   }

Don't Use DynamicEnum Accessors Before SDK Initialization

The initialization schema of the DynamicEnum value registry has been reimplemented using source generators instead of reflection. The registry is now created at a well-defined time during Metaplay SDK initialization rather than lazily on first use. As a result of this, the AllValues property as well as the TryFromId(), FromId(), TryFromName(), and FromName() accessors cannot be used before SDK initialization. Previously, it was allowed but with ill-defined behavior.

Migration Steps:

1. If the game server, client, or Unity Editor produces an error saying "DynamicEnum accessors AllValues, FromName(), and FromId() cannot be used before the Metaplay SDK core is initialized", investigate the stack trace to find the place where the access is happening.
2. Refactor the code to delay the access to happen after SDK initialization.

MetaDictionary Enumerator Type Change

To reduce the number of dependent generic types, MetaDictionary<TKey, TValue>.GetEnumerator() now returns an enumerator that doesn't implement IEnumerator<KeyValuePair<TKey, TValue>> as this isn't required in the typical case of enumerating dictionary entries directly.

To get an iterator of type IEnumerator<KeyValuePair<TKey, TValue>> you will have to explicitly invoke the IEnumerable<KeyValuePair<TKey, TValue>>.GetEnumerator() method by casting the dictionary first.

Migration Steps:

1. If you need IEnumerator<> of a MetaDictionary<,>, cast the dictionary into IEnumerable<> first:

   MetaDictionary<TKey, TValue> dict;
   
   IEnumerator<KeyValuePair<TKey, TValue>> enumerator = dict.GetEnumerator(); 
   IEnumerator<KeyValuePair<TKey, TValue>> enumerator = ((IEnumerable<KeyValuePair<TKey, TValue>>)dict).GetEnumerator(); 

GameConfigLibrary<TKey, TValue> Is No Longer new()able

As part of the GameConfig loading optimization efforst, the GameConfigLibrary class has been changed to abstract. If you were previously relying on the public parameterless constructor for creating empty config libraries, you'll need to use GameConfigLibrary<TKey, TValue>.CreateEmpty() instead.

Migration Steps:

1. If you use new GameConfigLibrary<,> to create an empty library, replace that with CreateEmpty():

   public GameConfigLibrary<ExampleId, ExampleId> ExampleLibrary { get; set; } = new GameConfigLibrary<ExampleId, ExampleId>(); 
   public GameConfigLibrary<ExampleId, ExampleId> ExampleLibrary { get; set; } = GameConfigLibrary<ExampleId, ExampleId>.CreateEmpty(); 

Replace Lists with Arrays in Custom IEnvironmentConfigProvider

The collection types in EnvironmentConfig have been changed from List<> into Array to both communicate they are immutable but also to reduce IL2CPP metadata initialization caused by List<> types. If you have implemented IEnvironmentConfigProvider and are supplying these values, you need to supply them as arrays instead.

Migration Steps:

1. If you have implemented IEnvironmentConfigProvider, and provide ClientLoggingConfig.LogLevelOverrides, create an array instead:

   MyEnvironmentConfigProvider.cs

   new ClientLoggingConfig
   {
       LogLevelOverrides = new List<LogLevelOverrideSpec>() { ... }, 
       LogLevelOverrides = new LogLevelOverrideSpec[] { ... }, 
   };

2. If you have implemented IEnvironmentConfigProvider, and provide ConnectionEndpointConfig.BackupGateways, create an array instead:

   MyEnvironmentConfigProvider.cs

   new ConnectionEndpointConfig()
   {
       BackupGateways = new List<ServerGatewaySpec>() { ... }, 
       BackupGateways = new ServerGatewaySpec[] { ... }, 
   };

Update Game Config Download URL

The API endpoint for downloading a GameConfig from server has been changed from GET /api/gameConfig/{id}?binary=true into GET /api/gameConfig/{id}/download.

Migration Steps:

1. If you have calls to fetch /api/gameConfig/{id}?binary=true, replace these with /api/gameConfig/{id}/download

   GameConfigDownloader.cs

   await httpClient.GetAsync($"{host}/api/gameConfig/{guid}?binary=true") 
   await httpClient.GetAsync($"{host}/api/gameConfig/{guid}/download") 

Final Validation

You should run the Metaplay integration test suite on your project after the SDK upgrade to make sure everything is still working as expected:

MyProject$ metaplay test integration