One File Per Actor

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

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.

One File Per Actor is enabled by default when using World Partition. The use of OFPA outside of a World Partition Level is currently considered Experimental and is disabled by default. To enable OFPA outside of World Partition:

  1. From the main menu, go to Edit > Editor Preferences.

  2. From the sidebar, select Experimental.

  3. Locate the Tools section and enable the check box for One File Per Actor.

Enabling One File Per Actor

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

The first method is to enable OFPA manually on individual Actors from the Details panel.

In some cases, you may want to enable OFPA for one Actor at a time. To do this, search for the Packaging Mode option in the Details panel, and select External from the dropdown menu.

Enabling OFPA for a single Actor.

After selecting this option, you will be asked if you want to enable the feature for all the Actors in the Level. Select Yes to convert all the Actors in the Level to OFPA or No to only enable it for the selected Actor.

You will need to save the newly created external packages for the Actor and the Level. Afterward, you won't need to save the Level again if you modify the Actor.

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

Enabling OFPA for a Level.

To do this, follow the steps below:

  1. Open the World Settings panel. From the main menu, go to Window > World Settings.

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

  3. After you enable this option, save the Level.

  4. You will be asked if you want to convert all Actors to external packaging. Select Yes to complete the conversion to OFPA.

    Click Yes to convert all the Actors in the Level.

Converting Sublevels

It is important to note that only the current Level will be converted to OFPA when you activate the Use External Actors option for your Level. To convert any of your sublevels, you must load them and enable the Use External Actors for each of them, as described above. Since this may be an issue if your Level contains several sublevels, you can use a commandlet to convert a Level and its sublevels automatically.

A breakdown of the commandlet.

Follow the steps below to use the commandlet:

  1. Open a Command Prompt window.

  2. At the prompt, navigate to the location of the UnrealEditor.exe file. For example: C:\Builds\Home_UE5_Engine\Engine\Binaries\Win64.

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

  4. Add the name of the commandlet and the following arguments:

    • -run="ConvertLevelsToExternalActorsCommandlet" is the name of the commandlet.

    • -nosourcecontrol tells the commandlet to not use source control.

    • -convertsublevels tells the commandlet to convert any sublevels the map may have.

  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 MainMap is the name of the map you wish to convert.

  6. Press Enter to run the commandlet. It will then convert the Level and any sublevels to OFPA.

Using 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 view and validate the contents of a changelist before you submit it using the View Changelist window.

An existing changelist for a level that uses OFPA.

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

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

For more information on using source control in Unreal Engine, see In-Editor Source Control.

When using OFPA, content and Actor files should be submitted to source control from within the Editor.

Changelist support is only available when using Perforce as your source control provider.

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