Dependency Analyser

The Dependency Analyser is a UE5 plugin to measure and analyse bottlenecks in asset dependency sizes. It allows for quick inspection of all assets in a project and identification of optimisation opportunities, thanks to its integration with the size map tool and the automated testing framework.

Table of Contents

• Introduction
  • The dependency problem
  • Specifications
  • Usage instructions
• Plugin Components
  • Dependency Analyser Tool
  • Dependency Analyser Test Suite
  • Dependency Analyser Settings
• Contributions
  • Known issues

Introduction

The dependency problem

Dependency chains are created by assets referencing other assets, and represent one of the biggest and most common problems with which developers on large projects have to deal when working in Unreal Engine. The reason why they are problematic lies in the way assets are managed in Unreal, which implies that whenever an asset is loaded, all its dependencies are loaded with it. It is not particularly easy to identify growing dependency chains until their size becomes obvious and starts impacting editor loading times, hurting developers' productivity. A great talk that explains the risks of complex dependency chains is Asset Dependency Chains: The Hidden Danger | Unreal Fest 2022 by Mark Craig.

This plugin simplifies the identification of asset dependencies by pointing a spotlight on their reference count and dependency chain size. It is an ideal tool to integrate into the testing framework and build pipeline of a project. Whilst dependency analysis can be carried out at any point during the development of a project, it is most efficient when performed regularly from the start, therefore an early integration is recommended.

Specifications

Dependency Analyser plugin version 1.0. Compatibility tested with Unreal Engine version 5.3.2 and 5.1.1.

Usage instructions

To use the Dependency Analyser plugin:

• Download this repository
• Move it to
  • the Plugins folder of your project, if you want to import it into a specific project
    • i.e. LyraStarterGame\Plugins
  • the Plugins folder of your engine, if you want to import it into any project
    • C:\Program Files\Epic Games\UE_[version]\Engine\Plugins on Windows
    • /Users/Shared/Epic Games/UE_[version]/Engine/Plugins on macOS
• Enable it by following the Unreal Engine guidelines
• Compile your C++ project (this repository does not contain binaries - users will need to compile the plugin autonomously) and open Unreal
• Navigate to Tools > Miscellaneous > Dependency Analyser to bring up the Dependency Analyser Tool
• Navigate to Tools > Test Automation and select DependencyAnalyser to inspect and run the Dependency Analyser Test Suite

Plugin Components

The Dependency Analyser plugin comprises of two main features:

• The Dependency Analyser Tool, which allows for an overview of the project asset dependencies
• The Dependency Analyser Test Suite, which uses the Automation System framework to include acceptance limits to asset dependency sizes

The settings of each of these tools can be customised via the Dependency Analyser Settings.

Dependency Analyser Tool

The Dependency Analyser Tool comprises of the following features:

1. Optional inclusion of soft references and dev folders into the results
2. Customisation of size in MB at which assets should be considered a warning (orange) or an error (red). These are reset every time the tool is reopened - to set them as default values, see Dependency Analyser Settings
3. Export of results of the analysis into a CSV file. Pressing the export button brings up the directory where the CSV file is saved, and a log is printed in console with the relevant path
4. Individual inspection of resulting assets
   • Right-clicking brings up a context menu including the options Open Size Map, Edit Asset or Find in Content Browser
   • Double-clicking bring up the Size Map inspector
5. Searchable results by Name or Type
6. Sortable results by Name, Dependencies Count, Total Size, Type or Path

Dependency Analyser Test Suite

If the project has the Functional Testing Editor plugin enabled, the Dependency Analyser offers a test suite to run a dependency analysis on all assets. The test is executed per-asset, so individual sizes of asset for each failing test can be identified.

The tests can be ran both via the Unreal editor and the console.

When running them via the editor, the results can be visualised by:

• Selecting the parent DependencyAnalyser test, for an overview of the duration and success/failure/warning rate
• Selecting the individual per-asset test, to visualise information about failure reason and asset size or reference count
• Inspecting the Message Logs, for an overview of failure reasons and asset sizes or reference counts of all assets for which a test ran

To run the tests via console command, you can use:

[PathTo]\UnrealEditor-Cmd.exe [PathTo]\[ProjectName].uproject Params=[LevelName] -ExecCmds=\"Automation RunTests Filter:DependencyAnalyser.[TestName];quit\" -nullrhi -nosound -nosplash -unattended -buildmachine -editortest -stdout

where [TestName] is either DependencyCountTest or DependencySizeTest. The results can be inspected through the console.

Dependency Analyser Settings

Users can customise error and warning sizes (both defaults and per asset type), and whether warnings should fail a test or not. These values can be customised by navigating to Edit > Editor Preferences > Advanced > Dependency Analyser and modifying the default values (or Type Limits for a higher degree of control), and Fail for Warnings.

Contributions

All rights to this plugin belong to YAGER. To contribute to the development of this plugin, feel free to open a Pull Request. If you want to actively be part of what we are developing at YAGER, check out and apply to any relevant open positions on our YAGER website.

Known issues

No known issues at the moment. If you find an issue, feel free to add it to the Issues page of this repository.