On-Demand BuiltData helps to optimize both network data and disk space usage while working on an Unreal Engine 4 project. It provides tools to omit BuiltData files while syncing to the newest version of the project from source control and then syncing them (or not) only when they are needed.
Depending on the size of the project and workflow of your team you’ll be able to save gigabytes, tens of gigabytes, or more of your network data usage and disk space, not to mention all the time spent waiting on the project to sync.
- Automatic syncing of BuiltData to the exact version of its map, not only the newest revision.
- Support for the Perforce source control system, including Content Browser, P4V, UnrealGameSync, and custom scripts.
- Can work automatically in the background, but allows for fine-grained control over which files to sync.
- Can sync BuiltData during cooking or other commandlets that run in unattended mode.
- Fix handling of files that are writeable but not checked out in the source control system.
- Fix handling of files that are opened by some other process and cannot be synced.
- Fix handling BuiltData files with a revision that is newer than its map.
To use On-Demand BuiltData plugin, you have to enable it first:
- Open ‘Plugins’ window. You can do this through ‘Edit’ menu in the menu bar.
- In the navigation panel, on the right side of the window, select ‘SourceControl’ group from ‘Installed’ section.
- In the list of plugins, on the left side of the window, find ‘On-Demand BuiltData’ plugin.
- Make sure that the plugin is marked as ‘Enabled’. You will have to restart the editor for this change to take effect.
From now on, each time the editor will try to load a BuiltData file that is out of sync with its map, you’ll be presented with the following popup:
Choosing the ‘Yes’ or ‘No’ option will sync or ignore this particular BuiltData file. Choosing the ‘Yes All’ or ‘No All’ option will sync or ignore BuiltData files for the whole map with all its sublevels. For some more complicated maps, this popup can be shown more than once even for ‘Yes All’ and ‘No All’ options (this can be fixed in future updates).
The popup will show both when BuiltData is older than its map, and when it’s newer. The latter case can occur when you’re working with a project that is out-of-date with the source control system.
The On-Demand BuiltData plugin can be configured to handle out-of-sync BuiltData files in multiple ways. This can be done through Project Settings:
- Open ‘Project Settings’ window. You can do this through the ‘Edit’ menu in the menu bar.
- In the navigation panel, on the right side of the window, scroll all the way down to the ‘Plugins’ category and click on the ‘On-Demand BuiltData’ section.
This setting controls the behaviour of the plugin in the Editor. It has three modes:
- Ask – Ask each time out-of-sync BuiltData file is accessed. This is the default behaviour that has been covered in the Basic Usage section of this documentation.
- Alway Sync – Sync out-of-sync BulitData always, without any interaction from the user.
- Never Sync – Always ignore out-of-sync BuiltData, without any interaction from the user.
This setting controls the behaviour when the plugin encounters a file that is writeable but is not checked out in the source control system. Such a file can have local changes that are not visible to the source control system. The file can be clobbered (overwritten) or left alone . It has three modes:
- Ask – Ask each time a writeable file is encountered. This is the default behaviour.
- Always Clobber – Clobber the file always, without any interaction from the user.
- Never Clobber – Always ignore the writeable file, without any interaction from the user.
Sync when Unattended
This setting controls the behaviour of the plugin in the unattended mode, e.g. while cooking. It is enabled by default.
Clobber when Unattended
This setting controls the behaviour when the plugin, in the unattended mode, encounters a file that is writeable but is not checked out in the source control system.
Sync without BuiltData
In the folder context menu of the Content Browser, you’ll find two new source control commands:
Sync (no BuiltData)
This command will sync the selected folder to their newest revisions in source control but will omit all the BuiltData files. BulitData files that are already synced, will be left at their current revisions.
This command will delete all the BuiltData files, that are not currently loaded. It will do this with the use of the source control system, so the server will know the files are missing from your computer. It is important, that you do not delete BuiltData files manually, because this can lead to desynchronization of your local state with the state on the source control server!
For the Perforce Visual Client (P4V) there is a set of custom tools that can be accessed through Depot/Workspace context menu. They’re written in Python, so there’s some work you’ll have to do before you’ll be able to use them.
Custom Tools installation
First, you’ll need to install Python (v. 3.6-3.8) which you’ll find here: python.org. If you’re not sure what to install, just grab the most convenient installer for your system and choose all the default options during the installation process.
Then you’ll need to install P4 integration for Python. Run the Command Prompt as an administrator:
- Press the Win key
- Type ‘cmd’
- Choose ‘Run as administrator’
In the Command Prompt type:
pip install p4python
The last thing to do is to import custom tools configuration into P4V:
- Run P4V.
- From the top menu bar choose ‘Tools > Custom Tools…’.
- In the bottom left corner of the ‘Manage Custom Tools’ window press the ‘Import Custom Tools…’ button.
- In the file dialog go to On-Demand BuiltData plugin folder (usually: C:\Program Files\Epic Games\UE_4.x\Engine\Plugins\Marketplace\ODBD).
- From the ‘Tools’ folder open the ‘p4v_tools.xml’ file.
- In the next window press the ‘Import button’.
In case your Unreal Engine 4 installation path differs from the default, you’ll have to edit script paths in tools. For each of the imported tools:
- Select the tool from the list.
- Press the ‘Edit…’ button.
- In the ‘Arguments’ field fix the path to the path of your Unreal Engine 4 installation.
- Press the ‘Ok’ button.
Get Latest Revision (no BuiltData)
This command will sync the selected folder to their newest revision but will omit all the BuiltData files. BulitData files that are already synced, will be left at their current revisions.
Get Revision (no BuiltData)
This command will sync the selected folder to the revision at the changelist typed in the prompt. The command will omit all the BuiltData files. BulitData files that are already synced, will be left at their current revisions.
Remove BuiltData from Workspace
This command will delete all the BuiltData files in your workspace. It will do this with the use of the source control system, so the server will know the files are missing from your computer. It is important, that you do not delete BuiltData files manually, because this can lead to desynchronization of your local state with the state on the source control server!
If your team uses the UnrealGameSync as the Perforce client, you can use ‘Sync Filter’ option to omit BuiltData files during sync:
- Open UnrealGameSync
- Press ‘Options’ button in the lower right corner of the window
- From the menu choose the ‘Sync Filter…’ option.
- In the ‘Custom View’ section of the ‘Sync Filter’ window type:
Next time you sync your project, you’ll be presented with the following window:
You can choose to remove (check) files or leave them (uncheck). This window will only appear once every time you edit Sync Filter options. On each sync after this BulitData files will be ignored, neither removed nor synced to the current revision.