One File Per Actor

An introduction to the One File Per Actor System and how it can be used in your projects

Windows
MacOS
Linux

In previous versions of Unreal Engine, when you wanted to make changes to one or more Actors inside a level, you needed to check the file out of source control. This locked other team members out of that file until your work was complete, slowing down the development process since only one person could work on a file at a time.

One File Per Actor (OFPA) reduces overlap between users by saving data for instances of Actors in external files, removing the need to save the main level file when making changes to its Actors.

The One File Per Actor feature is only available in the Editor. All Actors are embedded in their respective level files when cooked.

Enabling One File Per Actor

The One File Per Actor feature is designed to be granular and can be used several different ways.

The first way is to enable OFPA manually on individual Actors via the Details panel.

Enable OFPA with the Details panel

In some cases you may want to enable OFPA one actor at a time. To do this, locate the Packaging Mode option located in the Actor section and change the setting to External in the drop down menu. Once done, you will need to save the newly created external package for the Actor and the Level. Afterward, modifying the Actor will not require the level to be resaved.

After you save the level, you cannot undo this action by using the Undo command.

The second method is to enable One File Per Actor for use with the entire level.

Enable OFP using the World Settings panel

This is done by following the steps below:

  1. Open the World Settings by clicking on the Window menu and selecting the World Settings option.

  2. Navigate to the World section of the panel and click the checkbox next to Use External Actors to enable it.

  3. Once enabled, you will need to save the level.

  4. You will be presented with a prompt asking if you want to convert all Actors to external packaging. Select Yes to complete the conversion to OFPA.

Confirm dialog box

Converting Sub Levels

It is important to note that only the current level will be converted to OFPA when you activate the Use External Actors option on your level. To convert any of your sub levels, you will need to load them and activate Use External Actors in each of their World settings. Since this may be an issue if your level contains several sub levels, a commandlet has been provided to convert a level and its sub levels automatically.

Follow the steps below to use the commandlet:

  1. In Windows, open a Command Prompt window.

    Command Prompt

  2. At the prompt, begin by navigating to the location of the UE4Editor.exe file. For example: C:\Program Files\Epic Games\UE_4.26\Engine\Binaries\Win64.

    Command prompt with location

  3. Next, begin the command with the name of the .exe file that will run the commandlet, UE4Editor.exe.

  4. Add the name of the commandlet and the following arguments: -run="ConvertLevelsToExternalActorsCommandlet" -nosourcecontrol -convertsublevels

  5. Finish the command with the location of the level: "/Game/Maps/TestMaps/ExternalActors/MasterMap" In this example, Game is the name of your project and MasterMap is the name of the map you wish to convert.

    Command prompt with complete commandlet

  6. Press Enter and the commandlet will convert the level and any sublevels to OFPA.

OFPA With Source Control

While working in your source control application, you will notice that external Actor file names are encoded. To address this issue, you can now view and validate the contents of a changelist before it is submitted using the View Changelist window.

Using OFPA with in-engine source control

This window displays existing changelists and the files they contain. For external Actors, you can see the Actor names, level paths and types, rather than the encoded filenames.

With changelist support built into the Editor, you can validate the contents of your changelists before they are submitted to source control. This is required due to the added complexity that OFPA brings to your projects. For example, a user can checkout multiple files and only submit some of them, possibly leaving dangling references.

Content and Actor files should now be submitted to source control from within the Editor.

During Early Access, changelist support is only available when using Perforce as your source control provider.