CI and release verification

The Mass Forge source repository owns two maintainer verification entry points: Scripts/Verify-MassForge.ps1 for static, build, automation, and package gates; and Scripts/Test-MassForgeMultiplayer.ps1 for real dedicated/listen server processes. The same commands are used locally and by GitLab CI so the paths cannot silently drift. They depend on repository-only fixtures and are intentionally excluded from the distributable plugin package; run them only from a complete source checkout.

What the verifier proves

One successful run performs these gates in order:

1. Rejects generated source-tree directories, build/log debris, root-level or prototype-named plugin content, conflict markers, and unresolved task markers.
2. Checks local Markdown links between documentation files.
3. Cross-checks every customer-facing node, component, and completion event named by the Blueprint quick start against its public source declaration.
4. Verifies the isolated population-benchmark runner, its 10k/100k/1M defaults, correctness gates, memory/timing fields, and interpretation boundaries remain present.
5. Discovers every Mass Forge UMassProcessor, self-tests forbidden-pattern detection, and enforces bounded index/slot hot loops without name lookup, asset loading, dispatch, dynamic containers, allocation sites, reflection, text construction, logging, or container growth.
6. Requires the persistent-effect deadline heap and rejects Mass entity queries, chunk traversal, or entity iterators inside its bounded scheduler phase.
7. Runs Unreal Automation Tool BuildPlugin with strict includes and unity/shared PCH disabled by the packaging path.
8. Compiles Win64 Editor, Development Game, and Shipping Game targets using the engine supplied through -EngineRoot.
9. Creates a disposable blank host project from the packaged plugin.
10. Runs every MassForge automation test twice in separate unattended editor sessions.
11. Requires the exact expected test count, zero failures, zero per-test warnings/errors, and no Mass Forge or Automation Controller error/warning log lines.
12. Audits the distributable for forbidden build/test debris and unnamespaced root content, rejects repository-only maintainer Scripts, requires Installed=true and the Runtime/Editor module types, and verifies byte-exact authored Source, Content, Docs, Resources, README, and changelog payloads.

By default the verifier creates one uniquely named directory beneath the Windows temporary directory and removes it in a guarded finally block whether the run passes or fails. It does not create checkpoint folders beside the plugin.

What the multiplayer verifier proves

The multiplayer command strictly packages the plugin, builds the checked-in disposable C++ host under Tests/NetworkHarness, and launches four scenarios through separate Unreal processes:

1. one dedicated server, a first remote client, then a second late-joining remote client; and
2. one listen host followed by one late-joining remote client;
3. one dedicated server plus a hostile-input remote client; and
4. one listen host plus a hostile-input remote client.

The first participant receives a non-empty baseline with Health, a counted Gameplay Tag, a charged granted Ability, and an active Persistent Effect carrying an owner-scoped opaque reference. It submits a real owner RPC, observes the reliable receipt and backend completion, and receives the resulting Fast Array delta. The second participant must join after that mutation, receive the changed value as its initial baseline, submit another request, and make the first participant observe the shared authoritative update. The dedicated server must also observe connection teardown. Each hostile client submits an unknown/unowned source reference and must receive an authorization rejection, attempts an oversized nine-scalar wire payload, and confirms unchanged state; its server independently audits unchanged authoritative Health. Missing markers, wrong values, harness failure markers, crashes, timeouts, or build failures fail the command.

Every process uses deterministic latency/jitter emulation. The release defaults are -PktLag=80 and -PktLagVariance=20, configurable through -NetLagMilliseconds and -NetLagVarianceMilliseconds. This validates the exposed RPC and serializer boundary under delayed/variable delivery; it does not claim packet-loss recovery, raw socket fuzzing, or bandwidth saturation.

The fixture is test infrastructure and is excluded from the customer plugin package. By default its generated host, compiled files, and logs live under one uniquely named temporary directory and are removed through guarded, retrying cleanup.

Maintainer use from a source checkout

From the root of a complete Mass Forge source checkout in PowerShell 7, select one installed engine. These commands are not customer-package entry points:

pwsh -NoLogo -NoProfile -File Scripts/Verify-MassForge.ps1 `
    -EngineRoot 'C:\Program Files\Epic Games\UE_5.7'

The verifier reads Engine/Build/Build.version, reports the exact version, and creates its disposable host project with the matching major/minor engine association. Run it once for every baseline listed in ENGINE_VERSION_SUPPORT.md before release.

Use -ExpectedTestCount only when the suite intentionally changes, and update the CI default and roadmap evidence in the same commit. To inspect a package or report after a run, provide a new empty -OutputRoot outside the Mass Forge source checkout and -KeepArtifacts. The script refuses to overwrite an existing output directory or place active BuildPlugin output beneath the checkout, preventing recursive staging of earlier artifacts.

Run the real network gate with four free adjacent ports:

pwsh -NoLogo -NoProfile -File Scripts/Test-MassForgeMultiplayer.ps1 `
    -EngineRoot 'C:\Program Files\Epic Games\UE_5.7' `
    -BasePort 17881

Use a new empty -OutputRoot plus -KeepArtifacts when logs must be retained. Otherwise the command removes its workspace after success or failure.

Clean install and engine-specific distribution

After a BuildPlugin package passes the main verifier, prove the customer install boundary in fresh Blueprint and C++ hosts:

pwsh -NoLogo -NoProfile -File Scripts/Test-MassForgeCleanInstall.ps1 `
    -EngineRoot 'C:\Program Files\Epic Games\UE_5.8' `
    -PluginPackageRoot 'C:\MassForgeValidation\UE58\Package'

This loads and strictly validates all 115 shipping assets, runs authored-content automation, launches the Blueprint Quick Start runtime smoke, and compiles external Editor and Game targets against packaged public headers only with unity and PCH assumptions disabled.

Create a customer archive only after both gates pass:

pwsh -NoLogo -NoProfile -File Scripts/New-MassForgeDistribution.ps1 `
    -EngineRoot 'C:\Program Files\Epic Games\UE_5.8' `
    -PluginPackageRoot 'C:\MassForgeValidation\UE58\Package' `
    -OutputRoot 'C:\MassForgeDistribution\UE_5.8'

The distribution command refuses existing outputs, requires final non-beta legal/support metadata, copies the package into an isolated host, resaves all shipping content with the matching engine, repeats strict 115-asset validation, creates a versioned Win64 ZIP, and writes a SHA-256 manifest. -AllowReleaseCandidateMetadata exists only for clearly labelled non-publishable review builds, and the manifest records the override. Run it independently for UE 5.6, 5.7, and 5.8; never distribute one precompiled archive across engine lines.

GitLab runner contract

.gitlab-ci.yml defines one job per supported engine line. Each job expects a self-managed Windows runner with the common tags windows and unreal-engine, plus one version tag:

• ue-5-6
• ue-5-7
• ue-5-8

Each runner must use a PowerShell-capable executor and have Git and PowerShell 7 available. Define protected UE_5_6_ROOT, UE_5_7_ROOT, and UE_5_8_ROOT CI/CD variables pointing to the corresponding licensed engine installations. Engines are installed by the runner owner and are never downloaded by a job.

The three verify jobs and three dependent network jobs run for merge requests and the default branch. Each job builds in a runner-temporary directory outside the checkout, then copies the completed package, automation reports, network-process logs, and summaries into pipeline/job-specific .ci-artifacts/ directories for seven-day retention. This ordering prevents BuildPlugin from recursively copying its own output.

Current runner status

As of 2026-09-11, the private GitLab project exposes zero project runners, zero group runners, and zero instance runners. The pipeline definition is ready, but the roadmap CI gate remains open until compatible runners execute all three jobs successfully. Attaching runners changes external infrastructure and is intentionally not simulated by local success.

The final-source local matrix passed on 2026-09-21 against UE 5.6.1, UE 5.7.1, and UE 5.8.2. Every engine compiled the complete runtime/editor plugin in strict Editor, Development Game, and Shipping Game targets; ran two independent 39/39 automation passes with zero Mass Forge/test warning or error lines; matched exact hashes for all 494 authored payload files; and completed guarded cleanup. Clean-install validation then loaded 115/115 assets, passed authored-content automation and the Blueprint Quick Start runtime smoke, and compiled isolated external C++ Editor and Game targets on every baseline. Existing multiplayer certification remains engineering evidence but is outside the initial-release product promise and public example catalogue.