Skip to content

Linux server build

Scope

This page is the operational authority for compiling, cooking, staging, and archiving the Tank Game Linux dedicated server in Jenkins. It is a future-engine-change checklist, not a claim that the client-oriented Tank Game 5.8 working copy contains every server file.

The broad source migration and plugin compatibility history belongs in the UE AngelScript 5.8 upgrade. Creation and distribution of the engine image belongs in UE AngelScript build and distribution. This page starts at the point where Jenkins selects an engine image and a server source revision, then attempts to produce a deployable LinuxServer archive.

Repository and artifact boundaries

Do not use the local client checkout as proof that the Jenkins server source is ready. The build crosses three independently versioned inputs:

Input Authority Examples
Engine toolchain Immutable Jenkins image Unreal, AngelScript, Clang, engine plugins, Linux SDK
Server project source Exact repository and tag/commit checked out by the Jenkins TankGame job Metal_terraServer.Target.cs, server descriptor/config, server-specific plugin policy
Build automation Jenkins job/pipeline definition Image tag, mounts, preflight checks, temporary patches, UAT arguments, archive publication

Some fixes are intentionally server-specific. For example, the server target does not need to exist in a client-only checkout, and adding Linux to Journeyman Minimap's runtime allowlist matters specifically when the server cook loads assets that reference /Script/MinimapPlugin.

Other fixes may be shared, such as a Wwise compiler adaptation. Verify them in the repository that actually supplies the plugin source to Jenkins. Never infer that a fix is present in the server build because it exists in a different local checkout with a similar project name.

Before each engine transition, record together:

  • Jenkins job name and build number;
  • project repository URL and exact tag/commit;
  • engine image tag and immutable digest or checked artifact checksum;
  • build-automation revision;
  • whether any source transformations were applied before UAT.

Current verified reference

Jenkins TankGame build #508 is the verified UE 5.8 reference supplied for this procedure:

Job: TankGame
Engine image: tankgame/ue-as-build:5.8.2-f347f57-nouba
Target: Metal_terraServer
Platform: Linux
Server configuration: Development
Client: disabled
Archive: LinuxServer

Treat these values as an example of a known-good combination, not permanent names to copy into the next upgrade. A future build should select a newly versioned image and matching source revision rather than overwrite or retag the known-good image.

Future engine-change checkpoints

1. Pin the Jenkins inputs

  • [ ] Identify the exact server repository Jenkins will check out.
  • [ ] Pin an exact project tag or commit; do not validate an unrecorded branch head.
  • [ ] Select an immutable engine image version and record its digest.
  • [ ] Confirm the image was built from the intended engine and AngelScript revisions.
  • [ ] Preserve the previous known-good image reference for rollback.
  • [ ] Record the Jenkins pipeline revision that selects those inputs.

Changing only the Docker image is not an engine upgrade. The server target, project plugins, content, and automation must be accepted as one versioned combination.

2. Validate the engine image contract

Before compiling project code, verify inside the selected image:

  • [ ] /home/ue4/UnrealEngine/Engine/Build/BatchFiles/RunUAT.sh is executable.
  • [ ] Engine/Binaries/Linux/UnrealServer.target exists.
  • [ ] The image reports the expected Unreal and AngelScript revisions.
  • [ ] The Linux x86-64 SDK and compiler are available.
  • [ ] Required engine-owned plugins are present and built for Linux.
  • [ ] The container user can read the project mount and write the output and project-generated directories.
  • [ ] Container shared memory meets the image's UBA/runtime requirement; the UE 5.8 reference uses --shm-size=8g.

Image startup proves only the engine artifact. It does not prove that the mounted server source or its project plugins compile.

3. Validate the dedicated-server target in the server repository

  • [ ] Confirm Source/Metal_terraServer.Target.cs exists in the exact Jenkins source revision.
  • [ ] Confirm Type = TargetType.Server.
  • [ ] Update DefaultBuildSettings to the new engine's recommended value.
  • [ ] Update IncludeOrderVersion to the matching engine revision.
  • [ ] Confirm the target includes the intended game module and no client-only modules.
  • [ ] Compile the server target before attempting a full cook.

Inspect available target-rule values in the selected engine's TargetRules.cs. If a value is reported missing, first confirm Jenkins is using the expected image; an old UBT can make valid new target rules appear invalid.

Do not copy a client target wholesale. Server target type, compile definitions, plugin selection, and runtime dependencies can differ even when build settings versions match.

4. Audit plugin provenance and Linux eligibility

For every plugin enabled by the server project or referenced by cooked assets:

  • [ ] Identify whether Jenkins receives it from the engine image or server project repository.
  • [ ] Ensure there is only one authoritative copy.
  • [ ] Confirm its descriptor permits Linux on every runtime module needed by the server cook.
  • [ ] Confirm its module rules do not pull editor-only or unsupported platform dependencies into TargetType.Server.
  • [ ] Confirm its third-party headers and Linux libraries match the integration version.
  • [ ] Build or link it in the mounted project context; precompiled Win64 binaries are not evidence of Linux compatibility.

A plugin can be required during cooking even if the headless server does not execute its gameplay feature. Blueprint assets still need their native classes to load while the cooker resolves packages.

5. Separate durable source fixes from Jenkins patches

Jenkins may temporarily transform checked-out files to prove a compatibility fix, but automation must not become the long-term owner of project source.

  • [ ] Print each temporary transformation clearly in the build log.
  • [ ] Make transformations idempotent and fail if the expected source pattern is absent.
  • [ ] Apply them only inside the disposable Jenkins workspace.
  • [ ] Use cleanup traps when files are moved or stashed.
  • [ ] Open a source change in the repository that owns the affected file.
  • [ ] Remove the Jenkins workaround after the fixed source revision is tagged and a clean build passes without it.

The acceptance test for retiring a patch is a clean checkout of the tagged server source, built with no compatibility-edit stage. A green build that still rewrites source does not prove the durable fix was merged.

6. Compile gate before cooking

Run a focused Metal_terraServer Linux Development build, or the equivalent UBT invocation available in the image, before the full pipeline.

  • [ ] Server target rules compile.
  • [ ] UHT succeeds.
  • [ ] Project and project-plugin C++ compile with the image's Clang/libc++.
  • [ ] Linking succeeds.
  • [ ] The expected Linux server target receipt and executable are produced.

This separates target, compiler, and linker failures from content-cook failures.

7. Full BuildCookRun gate

The Jenkins-equivalent container invocation is:

docker run --rm --shm-size=8g \
  -v "/path/to/server-checkout:/project" \
  -v "/path/to/fresh-server-output:/out" \
  <immutable-engine-image> \
  /home/ue4/UnrealEngine/Engine/Build/BatchFiles/RunUAT.sh BuildCookRun \
  -project=/project/Metal_terra.uproject \
  -platform=Linux \
  -server \
  -serverconfig=Development \
  -noclient \
  -build \
  -cook \
  -stage \
  -pak \
  -archive \
  -archivedirectory=/out
  • [ ] Use a clean, writable archive directory.
  • [ ] Confirm UAT selects Metal_terraServer and the expected engine.
  • [ ] Build and cook finish with zero errors.
  • [ ] Stage, pak, and archive complete.
  • [ ] The archive contains the Linux server executable and required project content.
  • [ ] AngelScript bind data is present when required.
  • [ ] ldd reports no unresolved packaged executable dependencies.
  • [ ] Run a headless startup smoke test with representative server arguments.
  • [ ] Publish artifacts only after all gates pass.

Failure examples from the UE 5.8 transition

These incidents are examples of categories to recheck on future upgrades. They are not instructions to apply the same textual patch to every later engine.

Wrong engine image

The Jenkins job previously selected:

ghcr.io/epicgames/unreal-engine:dev-5.6.1

The verified UE 5.8 build selected:

tankgame/ue-as-build:5.8.2-f347f57-nouba

Lesson: make engine-image selection explicit and versioned. Verify the engine from inside the running container rather than trusting the job parameter name.

Server target build-environment conflict

The UE 5.8 server target needed:

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

Retaining V5 caused shared-build-environment conflicts with UnrealServer.

Lesson: migrate every target independently, including the server target that may live only in the server repository. Matching the game/editor settings is a useful starting point, but the authoritative check is compilation with the new engine.

Wwise and the new Linux compiler

Wwise 2025.1.10 declared std::is_signed specializations for its GTE number types. UE 5.8's Clang 20/libc++ rejected them. The temporary Jenkins workaround disabled both the template declaration and specialization in each affected file:

Plugins/Wwise/Source/AkAudio/Classes/GTE/Mathematics/BSNumber.h
Plugins/Wwise/Source/AkAudio/Classes/GTE/Mathematics/BSRational.h

Commenting only the struct line left an active template declaration and produced error: expected unqualified-id.

Lesson: compiler upgrades can expose invalid third-party standard-library customizations. Keep any workaround narrow, verify the exact plugin source Jenkins compiles, and replace it with an official compatible Wwise release or a reviewed source fix. Do not preserve a blind search-and-comment Jenkins patch across future plugin versions.

AngelScriptGAS cook crash

An older AngelScriptGAS plugin crashed UnrealEditor-Cmd during cook with signal 11, exit code 139, and Error_UnknownCookFailure. Installing the matching UE 5.8-compatible plugin fixed the crash. ActivationInfo and DynamicAbilityTags deprecations remained warnings.

Lesson: engine plugins are part of the engine-image contract. A successful server compile does not prove editor commandlets can load the plugin during cook. Match the plugin revision to the engine and run the full cook gate.

Minimap module absent during Linux cook

The server repository's MinimapPlugin.uplugin needed Linux in its runtime module PlatformAllowList. Without it, /Script/MinimapPlugin was unavailable to the Linux server cooker, causing hundreds of cascading Blueprint errors in Journeyman Minimap and the MiniMap Game Feature.

Lesson: the first missing native script module is the root cause; the later Blueprint errors are fallout. Apply this fix in the server repository or plugin source consumed by Jenkins. It need not be inferred from or forced into a separate client checkout whose target and platform policy differ.

Temporary automation hid missing source changes

For build #508, Jenkins applied compatibility edits before building: it disabled the two Wwise specializations and added Linux to the Minimap runtime allowlist. That established a working build combination but did not prove those fixes were present in the tagged server source.

Lesson: record pre-build mutations in build provenance. Promote the target, plugin, and compatibility changes into their owning repository, tag that source, then remove the Jenkins mutations and rerun from a clean workspace.

Failure diagnosis order

  1. Confirm Jenkins checked out the intended server repository and commit.
  2. Confirm the running container image tag, digest, Unreal version, and AngelScript revision.
  3. Review the log for pre-build source mutations.
  4. Run the server compile gate and resolve the first target, UHT, compiler, or linker error.
  5. During cook, find the first missing module or native class before addressing cascading Blueprint errors.
  6. Treat signal 11 or exit code 139 as a native commandlet/plugin crash and inspect the crash stack and plugin compatibility.
  7. Verify third-party Linux payloads and packaged dependencies.
  8. Only publish or deploy after archive validation and a headless startup test.

Promotion and rollback

For each future engine update:

  1. publish a new immutable engine image;
  2. prepare a server-source revision with durable compatibility changes;
  3. validate in a disposable Jenkins workspace without hidden manual edits;
  4. retain build logs, image digest, source commit, and archive checksum;
  5. promote the new combination only after server startup acceptance;
  6. keep the prior image and source tag available for rollback.

Rollback must select the previous known-good image and matching server source revision together. Mixing an old project tag with a new engine image is not a controlled rollback.