Fewer bugs—more FPS: how static analysis benefits Unreal Engine projects

Unreal Engine powers a growing number of projects—from the acclaimed "The Witcher" to the equally impressive "The Day Before" As projects scale, the cost of unnoticed errors rises dramatically. When code exceeds thousands of lines, even the most meticulous developer might overlook subtle bugs. Here PVS-Studio comes to the rescue, helping mitigate the risk of bugs infiltrating UE projects.

Introduction

Game development is a constant battle against bugs, and eliminating all errors remains an unattainable dream. Yet developers persist in seeking efficient ways to detect code vulnerabilities using diverse tools. This article explores one powerful ally for bug detection, particularly for Unreal Engine workflows.

PVS-Studio boasts extensive experience collaborating with Epic Games and Unreal Engine. With each release, it incorporates more mechanisms and UE-specific diagnostic rules. Let's examine the results of years spent refining PVS-Studio's integration with one of gaming's most popular engines.

Note. We've previously posted an article on the necessity of static analysis in GameDev using Unity Engine as an example.

PVS-Studio and plugins installation

Integrating PVS-Studio into Unreal Engine is straightforward. Download the installer via this link, follow the instructions to install PVS-Studio and the Visual Studio 2022 plugin. You will need an Enterprise license, if you don't have one, you can get a trial one at this link.

A quick-start guide for Windows is available in the documentation.

Ways to run the analysis

Attempting to analyze an Unreal Engine project with a usual Visual Studio plugin causes an error—analysis can't start. Unreal Engine uses its UnrealBuildTool (UBT) system, so analysis must launch through the UBT. Let's explore the first method via UBT flags.

UnrealBuildTool flags

So, Unreal Engine compiles projects via the UBT. To analyze a project, add this flag to the UBT:

-StaticAnalyzer=PVSStudio

Add it to theNMake Command Line field in project settings. This launches the analysis instead of the project build. The first run performs a full project scan, subsequent runs analyze only modified files (incremental analysis). Using this flag with theRebuildcommand forces a full project analysis each time.

Check out the documentation for detailed build and analysis scenarios.

Setting parameters in .target.cs files

For projects frequently regenerating .sln files or undergoing regular rebuilds, embed analysis parameters directly into .target.cs.

Add one line to theTargetconstructor based on your Unreal Engine version:

Unreal Engine 5.0 and earlier:

public MyProjectTarget(TargetInfo Target) : base(Target)
{
    ....
    WindowsPlatform.StaticAnalyzer = WindowsStaticAnalyzer.PVSStudio;
    ....
}

Unreal Engine 5.1 and later:

public MyProjectTarget(TargetInfo Target) : base(Target)
{
    ....
    StaticAnalyzer = StaticAnalyzer.PVSStudio;
    ....
}

Via the BuildConfiguration.xml file

If changing the .target.cs files is not possible, set the analysis parameters via a separate configuration file—BuildConfiguration.xml.

Minimal configuration example:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <StaticAnalyzer>
            PVSStudio
        </StaticAnalyzer>
    </BuildConfiguration>
</Configuration>

Excluding auto-generated and Unreal Engine core files

The *.gen.cpp files generated by Unreal Engine offer negligible value and slow analysis. Also exclude Unreal Engine source code from analysis unless you modify the engine.

To exclude auto-generated files, add the *.gen.cpp mask to the plugin's PathMasks setting. Note that Unreal Engine 5.4+ disables analysis of auto-generated files by default. To analyse them anyway, use the flag-StaticAnalyzerIncludeGenerated in the UBT.

Exclude Unreal Engine's core module via:

1. adding the flag to the UnrealBuildTool:

-StaticAnalyzerProjectOnly

2. adding target.cs in the file:

bStaticAnalyzerProjectOnly = true;

These settings significantly accelerate project analysis. For advanced parameters, grab a cup of tea and visit this page.

New in Unreal Engine project analysis

Redesigned report format and navigation

We revamped warnings generated via the UnrealBuildTool when running the analysis. PVS-Studio has long output reports in a new format featuring multi-file navigation. Earlier it was unavailable when running the analysis via the UnrealBuildTool, but now everything is working as it should.

Distributed builds and analysis via Horde + UBA

Unreal Engine 5.5 introduced a convenient bundle—Horde and UBA (Unreal Build Accelerator). It distributes builds (and now analysis) across networked machines with significant speed gains.

• Horde is an Epic Games' cluster build system that uses MongoDB and Redis. It can be installed via MSI or Docker.
• UBA is an executor enabling parallel build/analysis tasks for agents. You can enable UBA in a config file.

Analysis setup steps are given below.

1. Deploy Horde: host MongoDB and Redis, configure Horde, link your Epic Games account to GitHub, and accept the organization invite.
2. Agents: install HordeAgent on target machines, set ServerUrl, and Enroll.
3. Enable analysis: add StaticAnalyzer = StaticAnalyzer.PVSStudio; to .target.cs .
4. Configure: in BuildConfiguration.xml, enable bAllowUBAExecutor and specify Server and WindowsPool.

Builds and static analysis now distribute across agents, accelerating development—especially for large projects. Explore all features and settings at the link.

Memory optimization

PVS-Studio may consume more memory than desired during Unreal Engine analysis. There are two main reasons:

• Unity build (Single Compilation Unit). Unreal Engine merges multiple .cpp files into one, speeding up the build but demanding more analysis resources.
• Templates. UE's heavy template usage requires analyzing each instantiation, increasing load.

We optimized the C and C++ analyzer core to reduce memory usage and analysis time. However, for large projects, it is better temporarily disable Unity build as described here.

Unreal Engine-specific diagnostic rules

PVS-Studio includes UE-specific diagnostic rules:

V1100: Unreal Engine. Declaring a pointer to a type derived from 'UObject' in a class that is not derived from 'UObject' is dangerous. The pointer may start pointing to an invalid object after garbage collection.

V1102: Unreal Engine. Violation of naming conventions may cause Unreal Header Tool to work incorrectly.

If you have any ideas on new diagnostic rules, don't hesitate to share them with us. You can read more about this here.

Handling third-party libraries

We encountered interesting cases where diagnostic warnings "vanished" in UE projects—including our specific rules. Investigation revealed the MicrosoftPlatformCodeAnalysis.h file in the engine codebase, containing //-V:: (number) comments. They disable diagnostic rules project-wide including your code.

To solve the problem, we added the flag --analysis-paths mode=path to ignore suppressions from third-party code. It has the following modes:

1. mode is a set of the following values:

• skip-analysis excludes specified files/directories from analysis;
• skip-settings ignores settings from specified files/directories;
• skip combines skip-analysis and skip-settings functionalities.

2. path are files/directories to which settings apply.

If you're building a project with the flag -StaticAnalyzerProjectOnly, UnrealBuildTool automatically passes the --analysis-paths flag with appropriate parameters. This enables to analyze only your project while ignoring Unreal Engine core and unwanted suppressions.

You can read more about the problem and ways to eliminate it here.

Conclusion

PVS-Studio integrates seamlessly into existing build systems. Incorporating it early reduces release surprises. Try checking your Unreal Engine project for free with PVS-Studio at the link.

Thank you for reading!