Skip to content

Unreal Engine AngelScript 5.8 upgrade

Scope and authority

This page records durable findings from upgrading the Tank Game test copy from the UE 5.6 project state to the Hazelight UnrealEngine-Angelscript 5.8 line. It describes the current verified development baseline, not a released build.

The working engine identifies itself as UE 5.8.2 and was built from the angelscript-master branch at commit f347f57f05e992976b6c2be6612303b7e8099502. The project upgrade work happened in the isolated Tank Game 5.8 copy so the UE 5.6 project remained available for comparison.

Related project-specific plugin behavior is maintained separately:

Verified baseline

The following checks completed successfully:

Component Verification
UE AngelScript editor UnrealEditor source build succeeded
Shader worker ShaderCompileWorker source build succeeded
Engine Marketplace tools Auto Size Comments, Blockout Tools, Blueprint Assist, Electronic Nodes, and Tab Restore compiled together
Initial project plugin set 19 explicitly selected modules compiled together
Journeyman's Minimap Final merged UE 5.8 plus local-patch module compiled in project context
Lyra dependencies CommonGame, CommonUser, ModularGameplayActors, and UIExtension compiled in project context
Wwise Wwise 2025.1.10 integration modules compiled against the matching Win64 SDK payload
Nakama Pristine official 2.11.5 runtime and Blueprint modules compiled; full project link and focused recovery test passed
UE AngelScript Installed Build Development-only Win64 BuildGraph completed; editor-only Installed Build startup and asset-registry initialization passed
Linux dedicated server UE 5.8.2 AngelScript image compiled, cooked, staged, packaged, and archived Metal_terraServer with UAT exit code 0 and no cook errors; Jenkins TankGame build #508 later verified the pipeline with temporary compatibility patches

The initial Linux result was an isolated Jenkins-equivalent proof of concept. Jenkins TankGame build #508 later verified the UE 5.8 server build using tankgame/ue-as-build:5.8.2-f347f57-nouba, but Jenkins still applied temporary Wwise and Minimap source patches. A clean build from tagged server source with those fixes committed remains the durable-source gate. The clean full Win64 editor/game build and release checklist remain separate gates.

Build settings migration

UE 5.8 rejected the old target defaults with the outdated BuildSettingsVersion diagnostic. Both project targets now use:

DefaultBuildSettings = BuildSettingsVersion.V7;
IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_8;

The affected target files are:

  • Source/Metal_terra.Target.cs
  • Source/Metal_terraEditor.Target.cs
  • Source/Metal_terraServer.Target.cs

Changing only the editor target is insufficient because game, editor, server, and packaging workflows evaluate different targets.

Preprocessor findings

WITH_STEAMWORKS

V7 build settings no longer tolerate using an undefined identifier as if it were always available. Tank Game's module rules explicitly define WITH_STEAMWORKS=1 for supported Win64/Linux targets and 0 elsewhere. Source guards were made definition-safe where necessary:

#if defined(WITH_STEAMWORKS) && WITH_STEAMWORKS

Preserve the existing !UE_SERVER condition at call sites that are intended for clients only.

WITH_UNREALED was invalid

WITH_UNREALED was never defined by the UE 5.6 project, the UE 5.8 test copy, or the AngelScript engine. It incorrectly disabled ordinary editor-only FEditorDelegates::EndPIE cleanup. Those guards now use only:

#if WITH_EDITOR

This is valid because Metal_terra.Build.cs already adds the UnrealEd private dependency whenever Target.bBuildEditor is true. Do not reintroduce WITH_UNREALED.

C++ and UHT compatibility changes

Blueprint property categories

UE 5.8 UHT requires explicit Category metadata for properties exposed to the editor or Blueprints when a module is treated as an engine module. This first surfaced in BuildingGenerator. Add a meaningful category to exposed properties rather than disabling the check.

Project plugins should remain project plugins unless there is a real reason to install them into the engine. Besides ownership clarity, this avoids applying engine-module constraints merely because a plugin was copied into Engine/Plugins.

Nakama JSON object keys

UE 5.8 represents FJsonObject keys using FSharedString. Nakama code that assumed an FString key now materializes one explicitly, for example:

FString(Entry.Key.ToView())

Official Nakama Unreal 2.11.5 contains this UE 5.8 adaptation. The project uses that pristine upstream version instead of carrying the earlier local account-device, match-type, realtime-error, and session conversion edits. This is an API adaptation, not a change to the JSON wire format.

Nakama 2.11.5 lifecycle and refresh ownership

The upgrade replaced Nakama Unreal 2.11.0 and its temporary local PIE teardown patch with pristine official 2.11.5. Upstream 2.11.3 introduced weak client captures and explicit cancelled-request outcomes; 2.11.5 added UE 5.8 compatibility. Together these fixes address HTTP completions that arrive after the owning client is released during End PIE without maintaining a project fork of the plugin.

Nakama 2.11.5 also enables pre-request session refresh and transient HTTP retries by default. Tank Game deliberately disables both immediately after creating UNakamaClient:

Client->bAutoRefreshSession = false;
Client->bEnableRetries = false;

This is an ownership boundary, not a missing upgrade step. UNakamaConnectionSubsystem remains the single owner of proactive session refresh, refresh-token expiry fallback, EOS identity generation changes, reauthentication, realtime reconnection, stale callback rejection, backend readiness/failure state, and recovery backoff. Upstream auto-refresh runs only when an authenticated HTTP request is submitted near access-token expiry and does not replace those behaviors. Upstream retries are also disabled so non-idempotent House RPCs are not repeated independently of project policy.

Do not enable either plugin flag or remove the project recovery coordinator without redesigning and retesting that complete ownership contract. See Nakama client session recovery.

Git source-control provider interface

The bundled project copy of UEGitPlugin required UE 5.8 source-control provider interface updates. The adaptation includes the branch-at-index query, soft revert declaration, and optional change-state queries. Deprecated methods that became final in UE 5.8 must not continue to be overridden.

RuntimeAdminConsole

RuntimeAdminConsole compiled, but its StructUtils usage produced a deprecation warning. It is non-blocking for the present migration and should be handled before the deprecated API becomes an error in a later engine upgrade.

Plugin ownership and placement

Plugin location is an ownership decision, not merely a way to make a build pass.

Engine Marketplace plugins

The AngelScript engine contains the UE 5.8 Marketplace copies of:

  • Auto Size Comments
  • Blockout Tools
  • Blueprint Assist
  • Electronic Nodes
  • Tab Restore

These tools are editor-wide and were compiled against the custom engine.

The AngelScript engine also owns AngelscriptGAS and AngelscriptEnhancedInput; these are engine plugins and must be rebuilt against the matching AngelScript engine revision.

Project plugins

The following remain beneath Tank Game 5.8/Plugins so their source, local patches, and binaries travel with the project:

  • BuildingGenerator
  • GameFeatures, including Minions and TankInventory_Base
  • Hermes
  • Journeyman's Minimap
  • Lyra's CommonGame, CommonUser, ModularGameplayActors, and UIExtension
  • Nakama, using pristine official version 2.11.5 with project-owned recovery policy
  • RedTalaria
  • RuntimeAdminConsole
  • UEGitPlugin
  • Wwise, WwiseSoundEngine, WwiseNiagara, and WwiseMotionOpenXRHelpers

Do not keep duplicate copies of a plugin in both the engine and project. Unreal plugin discovery can select the wrong rules assembly or report a duplicate plugin name, and stale binaries can obscure which source was actually built.

AngelscriptGAS editor startup ordering

The editor-only AngelscriptGAS integration refreshes AngelScript Gameplay Cue classes after script compilation. AngelScript's initial compile runs while startup modules are still loading, before engine subsystems are fully initialized. Calling UAbilitySystemGlobals::Get() from that first PostCompile callback lazily initializes GAS and the Gameplay Cue object libraries too early. Cue asset loading can then trigger re-entrant Blueprint loading or compilation that accesses uninitialized engine/editor subsystem state.

This is an initialization-order hazard in the integration, not a Gameplay Tags configuration problem and not specific to one Blueprint type. The callback is under WITH_EDITOR, so the issue applies to Unreal Editor and editor commandlets, not packaged game targets.

The engine-side implementation now defers the initial Gameplay Cue refresh until OnPostEngineInit; subsequent AngelScript recompiles refresh normally. Keep this change in the engine's Engine/Plugins/AngelscriptGAS source and rebuild the plugin with the same engine revision. Do not retain a separate project copy once the rebuilt engine plugin is installed.

Lyra 5.6 to 5.8 reconciliation

Only the four Lyra plugins present in Tank Game were compared with Epic's official Unreal Engine repository:

  • CommonGame
  • CommonUser
  • ModularGameplayActors
  • UIExtension

The comparison used official UE 5.6 commit cdda65cecacd9a1278020925c357bf4cc0b17e8c and UE 5.8 commit f37e65bb8886823e8cda3c9e1b3931934f012e2d. It intentionally did not import unrelated Lyra sample plugins.

Verified official changes included:

  • making UGameUIPolicy tolerate a missing owning UI manager;
  • joining the first quick-play result directly;
  • accepting duplicate reservation responses as successful reservations;
  • updating presence property insertion to AddVariant;
  • adding UE inline-generated-CPP includes.

The local UIExtension logging and GetExtensionPointTag() accessor were kept as project overrides. See the UIExtension patch. ModularGameplayActors matched the official source without a semantic local delta. Line-ending-only differences were not treated as custom code.

Journeyman's Minimap reconciliation

The UE 5.8 Marketplace source was used as the new base, then the maintained Tank Game lifecycle and debugging changes were reapplied. The final plugin is kept in the project rather than the engine because developers must share and review those source patches.

An intermediate build exposed deprecated direct access to scene-capture show flags. The final merge uses the UE 5.8-compatible implementation and compiled successfully. The durable local behavior is described in the Journeyman minimap patch.

The plugin descriptor must also allow Linux. Without Linux in the PlatformAllowList, Unreal excludes MinimapPlugin from the server build and the cook reports hundreds of cascading Blueprint failures for missing /Script/MinimapPlugin classes. The Linux-enabled module compiled for both the Editor and Server targets in the proof of concept.

Wwise integration

The project uses Wwise integration 2025.1.10.9233.4458 and the matching Wwise SDK 2025.1.10.9233. For Win64 compilation, WwiseSoundEngine must contain at least the matching SDK include and x64_vc180 payload beneath its ThirdParty directory.

For Linux x86-64, overlay the matching SDK headers and Linux_x64 libraries into the integration's ThirdParty tree. Dedicated-server rules intentionally select Wwise's null/disabled SoundEngine path, while editor and cook tooling still require the matching SDK payload.

Clang 20.1.8 rejects Wwise GTE's std::is_signed specializations with -Winvalid-specialization. Scope a Clang diagnostic push/ignore/pop around only the BSNumber and BSRational specializations in AkAudio/Classes/GTE/Mathematics/BSNumber.h and BSRational.h. Do not use a module-level AdditionalCompilerArguments assignment: UE 5.8 ModuleRules does not expose that property.

The integration source without this payload fails while instantiating WwiseAuthoring, before compilation begins. Do not substitute a different 2025.1 patch SDK merely because its directory layout is compatible; keep the integration and SDK patch/build versions aligned.

Build-output hygiene

Old UE 5.6 plugin Binaries and Intermediate trees must not be trusted after the engine change. Remove or move them aside before the first authoritative UE 5.8 build. Prefer recoverable relocation during investigation, then delete the backup after the new build and project launch are verified.

Generated solution files and the local .uproject association are machine state. They are not evidence that every target or plugin compiled.

Installed Build bootstrap findings

Fresh engine source does not include generated UnrealBuildTool host binaries. UE 5.8 normally runs UnrealBuildTool.dll through dotnet, but InstalledEngineBuild.xml directly invokes UnrealBuildTool.exe while compiling rules assemblies. Upstream BuildUBT.bat considers the tool current when only the DLL exists, so a missing Windows apphost is not repaired. The AngelScript engine bootstrap now requires both artifacts on Windows and republishes UBT if either is absent.

Installed Build symbol stripping also requires pdbcopy.exe from the Windows SDK's Debugging Tools for Windows component. Treat both UBT artifacts and PDBCopy as preflight requirements, not failures to discover after native compilation.

The internal Installed Build pins GameConfigurations=Development; leaving the option at its graph default unnecessarily builds Shipping and DebugGame game targets. A retry of the exact same failed graph uses -Resume. Omitting -clean preserves native outputs, but by itself does not retain BuildGraph's completed-node state.

Repeatable validation

Use module-filtered builds while resolving individual compatibility issues:

$EngineRoot = "T:\UnrealEngine-Angelscript"
$ProjectFile = "T:\Repo\Tank Game 5.8\Metal_terra.local.uproject"

& "$EngineRoot\Engine\Build\BatchFiles\Build.bat" `
  Metal_terraEditor Win64 Development `
  "-Project=$ProjectFile" `
  -WaitMutex -NoHotReloadFromIDE `
  -Module=MinimapPlugin

Once focused builds pass, run the release-relevant clean targets rather than assuming a set of module DLLs proves the entire project. At minimum validate:

  1. a clean Metal_terraEditor build;
  2. editor startup and project load;
  3. Blueprint compilation and representative maps;
  4. game and dedicated-server targets;
  5. clean cook/package;
  6. Wwise initialization and bank workflow;
  7. PIE teardown, especially Nakama and minimap lifecycle cleanup.

The clean-cook requirements in the release checklist still apply.

Upgrade rules for the next engine revision

  1. Preserve a known-good old-engine project for comparison.
  2. Pin both the AngelScript engine commit and Epic upstream comparison commit.
  3. Compare locally patched plugins against both old and new upstream versions.
  4. Separate semantic changes from line endings and generated output.
  5. Keep editor-wide Marketplace tools in the engine and maintained source plugins in the project.
  6. Clear stale build outputs before accepting a new result.
  7. Build focused modules first, then execute clean full-target and packaging gates.
  8. Update the appropriate plugin patch page whenever a local override changes.