GDK for Unreal Release 0.12.0

English version

GDK for Unreal 0.12.0 (internal only)

Release notes

Unreal GDK version 0.12.0 has been released!

The GDK for Unreal 0.12.0 is an internal component release. The differences between this internal release and a public component release are:

• Minimal public documentation.
• No public announcement.
• The default branch is now a tag (0.11.0) where before it was a release branch. This allows us to give access to 0.11.0 to open platform customers without affecting Improbable pipelines or scripts. This also allows us to keep 0.12.0 as an internal release.

This release includes:

• Support for Unreal Engine 4.26 (we also support Unreal Engine 4.25 as the legacy version).
• Support for SpatialOS Runtime 15.0.
• Overhauled local deployment workflows with significantly faster local deployment start times (approximately 0.1s versus 7s).
• SpatialDebugger improvements.
• Load balancing workflow improvements.
• General workflow improvements.

See the changelog for full details.

WARNING: If you are an existing customer on the release GDK branch, and you use ‘git pull’, you will upgrade to 0.12.0. If you do not want this, switch to the 0.11.0 tag branch.

Follow these steps to upgrade your GDK, Engine fork and Example Project to the latest release.

Chinese version

虚幻引擎开发套件版本 0.12.0 (仅供内部参考)

版本发布说明

“虚幻引擎开发套件 0.12.0”是一次内部组件发布版本。相比公开组件版本，内部组件版本在以下方面有所区别：

• 对应的公开文档更简洁。
• 没有发布公告。
• 总体而言，现在的默认分支是一个标签 (例如：0.11.0)，而以前是作为一个发布分支 (release branch)。这种设置允许我们在不影响英礴流水线或脚本 (Improbable Pipeline/ Script) 的前提下，向公开平台用户开放 0.11.0 的访问权限；这也允许我们将 0.12.0 保留为一个内部版本。

本次版本发布包括：

• 支持虚幻引擎 4.26 (注：我们也继续支持虚幻引擎 4.25 作为历史版本)。
• 支持 SpatialOS 运行时 15.0。
• 全面修改了本地部署工作流，带来本地部署启动时间的显著提升 (约从 7 秒降低至 0.1 秒)。
• 改善了 SpatialDebugger。
• 改善了负载均衡工作流。
• 改善了一般流程。

更多信息，请参见 更新日志。

重要信息：如果您是发布版 GDK 分支 (release GDK branch) 的当前用户，且使用 “git pull”，那么您将升级至版本 0.12.0。如果您需要其他版本，可切换至较新的 0.11.0 标签分支。

如何升级版本？请点击此处，按照步骤将您的开发套件 GDK、引擎分支和示例项目升级到最新发布版本。

Upgrading

• You can find the corresponding UnrealEngine version(s) here.
• You can find the corresponding UnrealGDKExampleProject version here.

Follow these steps to upgrade your GDK, Engine fork and Example Project to the latest release.

You can read the full release notes here or below.

Join the community on our forums, or on Discord.

Happy developing,

The GDK team

---

Breaking changes:

• We no longer support Server Travel. This feature is being re-designed and will be reintroduced in a future version.
• The condition for sending Spatial position updates has been changed, the two variables PositionUpdateFrequency and PositionDistanceThreshold have now been removed from the GDK settings. To update your project:
  1. Set the value of PositionUpdateLowerThresholdCentimeters to the value of PositionDistanceThreshold and the value of PositionUpdateLowerThresholdSeconds to 60*(1/PositionUpdateFrequency). This makes sure that Actors send Spatial position updates as often as they did before this change.
  2. Set the value of PositionUpdateThresholdMaxCentimeters and PositionUpdateThresholdMaxSeconds to larger values than the lower thresholds.
     NOTE: If your project does not use custom values for the PositionUpdateFrequency or PositionDistanceThreshold then, by default, the updates will be sent with the same frequency as before and no action is required.
• Removed the OnAuthorityLossImminent Actor event.
• 'WorkerLogLevel' in Runtime Settings is split into two new settings - 'LocalWorkerLogLevel' and 'CloudWorkerLogLevel'. Update these values which will be set to 'Warning' by default.
• The Unreal GDK has been updated to run against SpatialOS 15.0. Older version of SpatialOS will no longer work with the Unreal GDK.
• In SpatialWorkerFlags.h some renaming took place around using delegates on flag changes.
  These functions and structs can be referenced in both code and blueprints and it may require updating both:
  1. Delegate struct FOnWorkerFlagsUpdatedBP has been renamed FOnAnyWorkerFlagUpdatedBP,
  2. Delegate struct FOnWorkerFlagsUpdated has been renamed FOnAnyWorkerFlagUpdated,
  3. Function BindToOnWorkerFlagsUpdated has been renamed to RegisterAnyFlagUpdatedCallback
  4. Function UnbindFromOnWorkerFlagsUpdated has been renamed to UnregisterAnyFlagUpdatedCallback
• Worker configurations must now be stored in the launch config for local deployments. These can be added in the SpatialGDKEditorSettings as before.
• Spot and SpatialD (Spatial Service) dependencies have been removed.
• Compatibility Mode runtime is no longer supported.
• Running without Ring Buffered RPCs is no longer supported, and the option has been removed from SpatialGDKSettings.
• The schema database format has been updated and versioning introduced. Please regenerate your schema after updating.
• The CookAndGenerateSchemaCommandlet no longer automatically deletes previously generated schema. Deletion of previously generated schema is now controlled by the -DeleteExistingGeneratedSchema flag.

Features:

• The DeploymentLauncher tool can be used to start multiple simulated player deployments at once.
• Schema bundles are generated by default (in addition to the schema descriptor). Specifying a Schema bundle location via -AdditionalSchemaCompilerArguments="--bundle_out=..." will result in the bundle being written to both the default location (build/assembly/schema/schema.sb) and the location specified by the additional arguments.
• Spatial Position Updates are sent based on a different logic. Previously, a position update was sent to Spatial if enough time had passed since the Actor's last update(computed using the SpatialUpdateFrequency) AND if the Actor had moved more than PositionDistanceThreshold centimeters. This change allows for Spatial position updates to be sent if any of the following is true:
  1. The time elapsed since the last sent Spatial position update is greater than or equal to PositionUpdateLowerThresholdSeconds AND the distance travelled since the last update is greater than or equal to PositionUpdateLowerThresholdCentimeters.
  2. The time elapsed since the last sent Spatial position update is greater than or equal to PositionUpdateThresholdMaxSeconds AND the Actor has moved a non-zero amount.
  3. The distance travelled since the last Spatial position update was sent is greater than or equal to PositionUpdateThresholdMaxCentimeters.
• New setting "Auto-stop local SpatialOS deployment" allows you to specify Never (doesn't automatically stop), OnEndPIE (when a PIE session is ended) and OnExitEditor (only when the editor is shutdown). The default is OnExitEditor.
• Added OnActorReady bindable callback triggered when SpatialOS entity data is first received after creating an entity corresponding to an Actor. This event indicates you can safely refer to the entity without risk of inconsistent state after worker crashes or snapshot restarts.
• Added support for the main build target having TargetType.Client (<ProjectName>.Target.cs). This target is automatically built with arguments -client -noserver passed to UAT when building from the editor. If you use the GDK build script or executable manually, you need to pass -client -noserver when building this target (for example, BuildWorker.bat GDKShooter Win64 Development GDKShooter.uproject -client -noserver).
• Added ability to specify USpatialMultiWorkerSettings class from command line. Specify a SoftClassPath via -OverrideMultiWorkerSettingsClass=MultiWorkerSettingsClassName.
• You can override the load balancing strategy in-editor so that it is different from the cloud. Set Editor Multi Worker Settings Class in the World Settings to specify the in-editor load balancing strategy. If it is not specified, the existing Multi Worker Settings Class defines both the local and cloud load balancing strategy.
• Added BroadcastNetworkFailure with type OutdatedClient on client schema hash mismatch with server. Add your own callback to GEngine->NetworkFailureEvent to add custom behaviour for outdated clients attempting to join.
• You can see the Spatial Debugger in-editor mode similar to the one you see in play mode. Select Spatial Editor Debugger from the drop-down menu on the Start Deployment button on the toolbar to toggle the visibility of the worker boundaries on and off in-editor.
• Enabled the bUseSpatialView property by default and added the --OverrideUseSpatialView flag.
• Added facilities to manipulate worker interest and Actor authority in SpatialFunctionalTest.
• Allow specifying the locator port via ?locatorPort= URL option when performing client travel.
• You can now enable/disable the multi-worker load balancing strategy with an in-editor toggle so that no Uasset files are changed. Select Enable Multi-Worker from the drop-down menu on the Start Deployment button on the toolbar to use the multi-worker strategy or de-select to use a single worker strategy in the editor. The Enable Multi-Worker toggle in World Settings and the command line option -OverrideMultiWorker have been removed as they are now redundant.
• Enabled packaging the command line arguments when building a mobile client by default.
• Added settings for the positioning and opacity of the Spatial Debugger worker region visualisation.
• You can now configure what the Spatial Debugger visualises in an in-game menu. Use F9 (by default) to open and close it. The key can be changed through a setting on the Spatial Debugger object.
• Added a setting for the Spatial Debugger to visualise all replicated actors in the local player's hierarchy, instead of just the player's controller, player state and pawn.
• You can now see worker information displayed on the worker's boundaries. The worker name and virtual worker ID displayed corresponds to the worker that you are currently looking at and will be visible when you are near a border.
• You can now filter logs for Local and Cloud deployments separately with Editor settings. The 'WorkerLogLevel' GDK setting was removed and has been replaced by 'LocalWorkerLogLevel' and 'CloudWorkerLogLevel'.
• You can now disable logging to SpatialOS for local and/or cloud deployments from the GUI (Project Settings -> Runtime Settings -> Logging). The command line argument -NoLogToSpatial can still be used for that as well.
• Servers now log a warning message when detecting a client has timed out.
• Handover is now optional depending on whether the load balancing strategy implementations require it . See RequiresHandoverData
• Improved the failed hierarchy migration logs. The logs are now more specific, the frequency of repeated logs is suppressed and cross-server migration diagnostic logs have been added.
• You can now select an actor for SpatialOS debugging in-game. Use F9 (by default) to open the Spatial Debugger in-game config menu and then press the Start Select Actor(s) button. Hover over an actor with the mouse to highlight and right-click (by default) to select. You can select multiple actors. To deselect an actor right-click on it a second time. If there are multiple actors under the cursor use the mouse wheel (by default) to highlight the desired actor then right-click to confirm your selection.
• SpatialWorldSettings is now the default world settings in supported engine versions.
• Worker SDK version compatibility is checked at compile time.
• SpatialWorkerFlags has reworked how to add callbacks for flag updates:
  1. BindToOnWorkerFlagsUpdated is changed to RegisterAnyFlagUpdatedCallback to better differentiate it from the newly added functions for register callbacks.
  2. RegisterFlagUpdatedCallback is added to register callbacks for individual flag updates
  3. RegisterAndInvokeAnyFlagUpdatedCallback & RegisterAndInvokeFlagUpdatedCallback variants are added that will invoke the callback if the flag was previously set.
• Overhauled local deployment workflows. Significantly faster local deployment start times (0.1s~ vs 7s~).
  • Switched to using binary (standalone) versions of the Runtime and Inspector which allow us to start deployments much faster.
  • Runtime and Inspector binary fetching is now handled by the GDK. To fetch these binaries you must start the game project at least once.
  • The Runtime and Inspector will be restarted between each Editor session.
  • Support for standalone launch configurations introduced, these are now generated by default for your local deployments, worker configurations for local deployments are now stored inside the launch config.
    • Generated local launch configs can still be found in <GameProject>\Game\Intermediate\Improbable\<MapName>_LocalLaunchConfig.json.
  • Cloud deployments still use the older launch config and worker config format, we still generate these automatically for your maps.
    • Generated cloud launch configs can be found in <GameProject>\Game\Intermediate\Improbable\<MapName>_CloudLaunchConfig.json.
  • The Launch Configuration Generator tool can be used to generate either local or cloud launch configs via a checkbox in the GUI.
  • Compatibility Mode Runtime is no longer supported.
  • Local deployment logs timestamp format has changed to yyyy.mm.dd-hh.mm.ss. Example log path: <GameProject>\spatial\logs\localdeployment\2020.12.02-14.13.39
  • Launch.log no longer exists in the localdeployment logs, the equivalent logs can be found in the runtime.log
  • Local deployments are now restarted by default when using PIE. We recommend this setting for all your projects.
  • Snapshots taken of running local deployments are saved in <GameProject>\spatial\snapshots\<yyyy.mm.dd-hh.mm.ss>\snapshot_<n>.snapshot
  • Inspector URL is now http://localhost:33333/inspector-v2
  • Inspector version can be overridden in the SpatialGDKEditorSettings under Inspector Version Override
• The SpatialNetDriver can disconnect a client worker when given the system entity ID for that client and does so when GameMode::PreLogin returns with a non-empty error message.
• Unreal Engine version 4.26.0 is supported! Refer to https://documentation.improbable.io/gdk-for-unreal/docs/keep-your-gdk-up-to-date for versioning information and how to upgrade.
• Running with an out-of-date schema database reports a version warning when attempting to launch in editor.
• Reworked schema generation (incremental and full) pop-ups to be clearer.

Bug fixes:

• Fixed a bug that stopped the travel URL being used for initial Spatial connection if the command line arguments could not be used.
• Added the Handover tag to APlayerController::LastSpectatorSyncLocation and APlayerController::LastSpectatorSyncRotation in order to fix a character spawning issue for players starting in the Spectating state when using zoning.
• No longer AddOwnerInterestToServer unless the owner is replicating, otherwise this warning fires erroneously: "Interest for Actor is out of date because owner does not have an entity id."
• Properly handle pairs of Add/Remove component in critical section. The issue manifested in the form of remnant actors which the worker should have lost interest in.
• Made the DeploymentLauncher stop multiple deployments in parallel to improve performance when working with large numbers of deployments.
• Fixed an issue where possessing a new pawn and immediately setting the owner of the old pawn to the controller could cause server RPCs from that pawn to be dropped.
• Added support for the bHidden relevancy flag. Clients will not checkout Actors that have bHidden set to true (unless they are always relevant or the root component has collisions enabled).
• Fixed an issue with deployments failing due to the incorrect number of workers when the launch config was specified, rather than automatically generated.
• Fixed the too many dynamic subobjects error on Clients appearing when a Startup Actor, with one dynamic subobject was leaving and re-entering interest multiple times. Added the RemovedDynamicSubobjectObjectRefs map in USpatialPackageMapClient that keeps the dynamic subobjects removed from Startup Actor's client's interest to avoid duplication of the dynamic subojects when the Startup Actor re-enters the Client's interest.
• Fixed an issue that prevented the Interest component from being initialized properly when provided with Worker_ComponentData.
• Cleaned up startup logs of a few noisy messages.
• Fixed a crash that sometimes occurred upon trying to resolve a pointer to an object that has been unloaded.
• Fixed a crash when spawn requests are forwarded but the APlayerStart actor is not resolvable on the target worker.
• By default, only an Actor's replicated owner hierarchy is used when determining which worker should have authority over an actor. Non-replicated Actors are now ignored.
• Fixed a crash that would sometimes occur when connection to SpatialOS fails.
• Fixed a crash that occurred when an actor subobject became invalid after applying initial component data.
• Non-replicated Actors net roles are not touched during startup.
• Fixed a bug which dropped component updates on authority delegation.
• The DeploymentLauncher checks the validity of the simulated players deployment name.
• Worker configuration watcher only rebuilds worker configs when *.worker.json files are changed.
• Added support for FPredictionKey's conditional replication logic. GameplayCues now activate on all clients, instead of only the client that initiated them.
• Fixed a bug where deployment would fail in the presence of trailing spaces in the Flags and LegacyFlags fields of the SpatialGDKEditorSettings.
• Fixed a crash that would occur when performing multiple Client Travels at once.
• Fixed an issue where bReplicates would not be handed over correctly when dynamically set.
• Add ServerOnlyAlwaysRelevant component and component set schema definitions
• Fixed a snapshot reloading issue where worker would create extra actors, as if they were loading on a fresh deployment.
• Server workers use TCP (instead of KCP) by default.
• Fixed a rare crash where a RepNotify callback can modify a GDK data structure being iterated upon.
• Fixed race condition in Spatial Test framework that would cause tests to time out with one or more workers not ready to begin the test.
• Fixed client connection not being cleaned up when moving out of interest of a server.
• Fixed an assertion being triggered on async loaded entities due to queuing some component addition.
• Fixed a bug where consecutive invocations of CookAndGenerateSchemaCommandlet for different levels could fail when running the schema compiler.
• Fixed a crash that occured when opening the session frontend with VS 16.8.0 using the bundled dbghelp.dll.
• Spatial Debugger no longer consumes input.
• Fixed an issue in the SpatialTestCharacterMigration test where trigger boxes sometimes wouldn't trigger at low framerates.
• Spatial bundles no longer requested at startup if UGeneralProjectSettings::bSpatialNetworking is disabled.
• Fixed an issue where heartbeats could be ran on a controller after its destruction
• Fixed an issue that led to the launch config being left in non-classic style with certain engine and project path configurations