Virtual Assets Quickstart Guide

Set up a simple deployment for Virtual Assets in your project.

Prerequisite Topics

In order to understand and use the content on this page, make sure you are familiar with the following topics:

This guide explains how to virtualize a small sample or test project.

1. Required Setup

This guide does not require a specific platform or template project, and you can follow along with any Unreal Engine project. However, your project must be set up to use Perforce as source control, and you need to set up the in-editor check-in workflow. For more information about Perforce setup, refer to Using Perforce as Source Control and Source Control Inside Unreal Editor.

You also need to set up a shared Derived Data Cache (DDC) for your project to act as your fast cache storage. For more information, refer to Derived Data Cache.

2. Config File Setup

Open your project's DefaultEngine.ini file and add the following text: 

[Core.ContentVirtualization]
SystemName=Default

[Core.VirtualizationModule]
BackendGraph=VABackendGraph_Example

[VABackendGraph_Example]
PersistentStorageHierarchy=(Entry=SourceControlCache)
CacheStorageHierarchy=(Entry=DDCCache)
SourceControlCache=(Type=p4SourceControl, DepotRoot="...")
DDCCache=(Type=DDCBackend)

This enables virtualization for all currently-supported assets. These settings have the following impact:

  • VABackendGraph_Filesystem defines a backend graph.

  • SourceControlCache defines your Perforce source control system as a backend for virtualized payloads and provides an alias to reference it with. Change the DepotRoot value to your project's root directory.

  • DDCCache defines your shared DDC as a backend for virtualized payloads and provides an alias to reference it with.

  • CacheStorageHierarchy sets DDCCache as your fast cache storage backend. If your project can find bulk data payloads here, it will prefer pulling that data from this source.

  • PersistentStorageHierarchy sets SourceControlCache as the persistent storage backend. This is a location where your project is guaranteed to find bulk data payloads if all other backends fail.

Refer to the Backend Graphs page for more details about defining backends for your project.

3. Virtualize a Package

After enabling Virtual Assets, any package you submit from the editor in your project should be virtualized when submitted. This will work for any editor submission method.

The Unreal Virtualization Tool can also submit change lists. The source code for the Unreal Virtualization Tool is located in Engine\Source\Programs\UnrealVirtualizationTool\. To use it, compile the tool, then run it in a command line with the following arguments: 

-ClientSpecName=[WorkspaceName] -Mode=Changelist -Changelist=[Changelist]

Command

Description

ClientSpecName

The name of the workspace to submit from.

Changelist

The changelist to virtualize and submit.

Normally you should not virtualize assets without submitting them. However, this tool makes it possible by adding -NoSubmit to the command line. The packages in the changelist will be virtualized, but the changelist itself will not be submitted.

4. Validate Your Virtualized Package

To determine whether your package has successfully virtualized, hover your mouse over the asset in the content browser and check the Has Virtualized Data entry.

Verify that your asset virtualized by hovering over it with your mouse cursor

Alternatively, you can look at the file size of the asset. If the .uasset file is significantly smaller than it was before you virtualized it, the bulk data was separated from the .uasset and is now contained in the Saved/VirtualizedPayloads directory.

To investigate the contents of the package file, right-click the asset in the Content Browser, click Copy File Path, then input the following command in the console: 

    DumpPackagePayloadInfo [file path]

Replace [file path] with the file path you copied from the Content Browser.

This console command can take either a full path or a package path, and it will write a summary of the payloads in the output window. The output displays a list of the locally stored payloads followed by a list of the virtualized payloads. DumpPackagePayloadInfo does not use any cached information, such as the asset registry. Instead, it re-parses the package's information each time you use it, so the information it provides should always be up to date.

Configure Virtual Assets for Your Project

Now that you have a basic implementation of Virtual Assets in place, you can configure it to suit your project's needs. The following pages provide more information about the ways you can customize your setup:

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Cancel