Epic Unreal Engine and Perforce for version control

A need arose for version control on various on-going Epic Unreal Engine (UE) projects. Our initial attempt with git/git-lfs was only partially successful.

Epic does have a page about version control. Essentially they suggest either Perforce or SVN. A bit of searching suggests most UE shops use Perforce. No one here had experience with Perforce and setting it up turned out to be more complicated than we assumed it would be. We freely admit this is probably our fault.

Here we describe how to setup up Perforce server and clients for an internal network (LAN) for multiple clients and users for UE projects. While it would be straight forward to allow WAN connections, to minimize the surface for external attacks, we decided not to do this. We have a mixture of computers running windows 10/11, Linux and macOS.

Here is the outline for this article:

Preliminaries

Perforce is based on a a server/client model. The server is the computer which will store the files (and all their revisions). In Perforce terms, this is a depot (we do not cover streams here). The clients pull and push files to the server based on a Workspace. A Workspace is also stored on the server and consists of a mapping of files in depots to local working files on a client machine. This local copy is fetched and changes are pushed back to the server according to a Workspace. Typically one depot is used for one UE project.

The first thing you need to do is download the server (called “Helix Core Server” but also referred to as “P4D“, confusingly on Windows we run an equivalent “P4S” service) and the client (called “P4V“) software for each target client machine (for macOS P4 and P4V are available from Homebrew while Linux often have packages). Regardless, after filling out some contact information (do expect Helix to contact you), the files can also be downloaded from here. This software is free assuming you have less than six users and 21 depots.

P4D and P4V installers on Windows 11. Install P4D (helix-core-server-x64.exe here) only on server. P4V installed on server and all clients.

The server will run on a machine that all clients will connect to, therefore it should stay up and awake to respond. Decide on the machine which will be the server. We start with the server. You need to find the hostname for the server. Our choice for a server is a Windows 11 computer. So, from the Start menu, type cmd and select Command Prompt (on macOS/Linux start a Terminal).

Click Start and then type ‘cmd

In the resulting Command Prompt window, type hostname followed by Enter.

Type hostname in the Command Prompt on the Server for the Server hostname (P-Server here)

You can change the hostname if you want by going to Start>Settings>System>About and hitting Rename this PC.

For the rest of this tutorial, we will use P-Server as the hostname of the server. You should substitute your hostname for P-Server.

Installation of Perforce server (P4D)

Install (as “Administrator“) “P4D” or Helix Core Server on the server machine (accepting defaults is fine). Click Next.

Installation of P4D on Server. Default options are fine.

Unless there is a need, use the default port “1666” for the Port Number. If you choose a different port, then simply substitute that port for “1666” for everything below. Click Next.

Unless there is need, Port Number default value of 1666 is fine.

When prompted for Client Configuration, in the Server field use “P-Server.local:1666” (appending “.local” to hostname allows a typical LAN to find the server). For User Name type in your first user for Perforce (suggest avoid using spaces or special characters). Click Next.

Put in the hostname for the Server appending “.local:1666“. Type in a user name (no spaces or special characters)

Install P4D on the server. Click Start.

Select Start to install P4D on server.

And the server will be installed. Click Finish.

Perforce server is installed

It should automatically start a Service for Perforce. You can check this by typing “Services” in the Start menu and then scrolling down the list and look for Perforce. Selecting Perforce, it should say the service is running.

A service called Perforce is shown to be running.

For other machines to reach the server, you need to open up port 1666 in the Windows firewall. From the Start menu type “Firewall & network protection” and hit Enter.

Click on the “Advanced settings” near the bottom center.

Select Advanced settings on lower center

On the left, you see a column. Double-click the “Inbound Rules”. On the right, click “New Rule…”.

Select Inbound Rules on left and then click on New Rule… on the right

On the next window, select “Port” and then click Next.

Select Port for type of rule

On this screen under Specified local ports, type in “1666” (w/o the quotes) and click Next.

Type 1666 for Specific local ports

Make sure “Allow the connection” is enabled and click Next.

Select Allow the connection

You can uncheck the “Public” option if you want or leave it be. Click Next.

Unchecking Public means the server will only accept incoming connections when connected to trusted networks only

For Name, use something descriptive, say “Perforce Server” and under Description say something like “incoming for Perforce Server”. Click Finish.

Give a descriptive Name and any additional information

You should now have the Perforce server running and it can accept incoming connections on port 1666.

Showing incoming connections to port 1666 for server.

Stay on the server machine for the next section.

Installing P4V

We will now install P4V (as Administrator). Under Select Applications, ensure all options are selected. Click Next.

Install dialog for P4V client. Ensure all options are selected

For Server field type in “P-Server.local:1666“. For User Name type in a user (either new or existing) typical for this client. Click Next.

Type in <hostaname>.local:1666 for Server. Enter a user (new or existing).

Click Install.

Yes, please, Install

Click Exit.

P4V is installed on a client

P4V should now start automatically (otherwise it can be started from the Start menu). Since this is a new install, it asks for a Connection.

Creating the first user

In the Open Connection dialog, confirm Server field is “P-Server.local:1666” (adding “.local” to end of hostname allows name resolution on a typical LAN). Type in a User (again no spaces or special characters) and it can be the same or different. We will soon make this user the super user. Since this is the first time setting up Perforce, click New… to the right of User.

For Server type in <hostname>.local:1666, type in user name and then click New… to the right of User

In the resulting dialog type in the User name again, if missing, the Full Name and Email. You can leave the Password blank (or not) but everything else must be filled out. Click Save.

Fill in Full Name and Email, password is optional

Create Users and Depots

From the Tools menu, select Administration (or from the Start menu run P4Admin)

To create users, depots, …, we run P4Admin from the Tools menu

It’s likely the following dialog box is presented. So this user will be special. You can still use it as a typical user.

Use this user in the future if you do further P4Admin tasks

Let’s create another user, but just a standard one. Select the Users & Groups tab in the center panel and then right-click in the panel and select New User... (or from File>New...>User...)

Create a New User (or select File>New>User…)

User, Email and Full name must be filled out. Type should be standard. Click OK.

Fill in User, Email and Full name and ensure Type is standard

Let’s create a depot for an UE project. From File>New...>Depot...

Create a new depot to hold an UE project

Type in a useful name for this depot corresponding to the UE project. Click OK.

This happens to be UE project name

Select local for Depot Type. Click OK

Select local for Depot type

The new depot should be present (may have to press the refresh button) under the Depots tab

Our new depot Vivaldi

And let’s delete the default depot (don’t have to, but…). Under the Depot tab in the center panel, right-click depot and select Delete Depot 'depot'

Deleting the default depot

Click Yes on the confirmation dialog.

Yes, please delete

You can create more Users or Depots (recall one depot for each UE project). Once you are done you can close P4Admin.

Setting up Perforce for UE projects

Now we need to tell Perforce what and how to store UE projects. Still on the server machine, open a new Command Prompt, type “p4 typemap” and press Enter (you must open a new Command Prompt after installing P4V).

In a new Command Prompt, type p4 typemap followed by Enter

This should open up Notepad.

Editing a typemap file using Notepad

Copy and paste the following to replace the default template:

# Perforce File Type Mapping Specifications.
#
#  TypeMap:             a list of filetype mappings; one per line.
#                       Each line has two elements:
#
#                       Filetype: The filetype to use on 'p4 add'.
#
#                       Path:     File pattern which will use this filetype.
#
# See 'p4 help typemap' for more information.
#
# this will be for all depots. if you want for specific depot do something like
#               binary+w //depot/....exe
# this list is inspired from https://docs.unrealengine.com/5.0/en-US/using-perforce-as-source-control-for-unreal-engine/
TypeMap:
                binary+w //....exe
                binary+w //....dll
                binary+w //....lib
                binary+w //....app
                binary+w //....dylib
                binary+w //....stub
                binary+w //....ipa
                binary //....bmp
                text //....ini
                text //....config
                text //....cpp
                text //....h
                text //....c
                text //....cs
                text //....m
                text //....mm
                text //....py
                binary+l //....uasset
                binary+l //....umap
                binary+l //....upk
                binary+l //....udk
                binary+l //....ubulk

Save the file by pressing control-S and then exit Notepad. The Command Prompt should then show “Typemap saved“.

Confirmation that typemap

Now we have typemap set for UE projects. In the same Command Prompt, type “p4 set P4IGNORE=.p4ignore” followed by Enter (no spaces around the “=” sign).

Type p4 set P4IGNORE=.p4ignore and press Enter

This completes the setup for the server.

Creating Workspace and populating depot from an existing UE project

Here we will start with an existing UE project. For bookkeeping, a good practice is to rename the UE project folder into the following format: <user>_<client machine>_<UE project name>. Our UE project is called Vivaldi so we rename the UE project folder to be lei_P-Server_Vivaldi.

Rename UE project folder name to lei_P-Server_Vivaldi

Now open up Notepad and copy the following into a new document

# based on https://www.perforce.com/products/helix-core/configure-helix-core-game-engine#tab-panel-76014
# User-specific folders or temporary files that should not be versioned.
	Saved/
	Intermediate/
	DerivedDataCache/
	FileOpenOrder/
	obj/
# Certain file types that should not be versioned.
	*.pbd
	*-Debug.*
# Visual Studio user settings files that should be ignored.
	.vs/
# Do not want macOS files
	.DS_Store

Type control-S to bring up the Save as dialog. Navigate into the UE project folder we just renamed. For Save as type select All files. Type in .p4ignore (notice the ‘.’ at the beginning) for File name. Click Save and close Notepad.

Navigate into UE project folder then .p4ignore for File name, All Files for Save as type then click Save

Going back to P4V, under the View menu, select Workspaces.

Select Workspaces from the View menu

On the right of the p4v window, select the Workspaces tab and then right-click in the pane below and select “New Workspace...“.

Create a New Workspace… by right-click on Workspace panel

For Workspace root, hit the Browse… button

Clcik Browse for Workspace root

and navigate to the folder which holds your UE project and click Select Folder.

For Workspace name, the convention is to do <user>_<client machine>_<project name>. After editing, confirm Workspace root is still pointing to the correct folder.

Confirm Workspace root is correct and ensure only the depot that has the UE project has green check (for all other depots, right click and select Clear)

Click on the Advanced tab and select Rmdir: delete workspace directories when empty and from the drop down menu for On submit, select Don't submit unchanged files. Click OK

Select Rmdir and Don’t submit unchanged files for On submit

Dismiss the next dialog box by clicking No since you want to use an existing project.

Select No to use existing files

We had problems using the Add Files Wizard, so click Cancel.

Select Cancel to avoid using Add Files Wizard

and dismiss the next dialog box by clicking Yes

Yes, really do please

Click the Refresh button on top left. Click on the Workspace tab on the left panel. Using control key, select Config, Content, Source, .p4ignore and *.uproject (Source folder is only present if using C++ in UE). Then right click on the *.uproject and select Mark for Add...

Under Workspace panel on left, select Config, Content, Source, .p4ignore and *.uproject. Then right-click and select Mark for Add…

On the next dialog, select New for the drop down menu and type in description and then click OK

Select New on drop down menu and type in a description

Now on the right, click the Pending tab and right-click on the changelist you just created and select Submit...

Under the Pending tab on the right, right-click on the new changelist and select Submit…

In the resulting dialog, you can add to the description if you want. Then click Submit.

Add to description and then click Submit

P4V will then add these new files to the depot (may take awhile depending on size of UE project)

Example progress of creating a new depot

Congratulations, you have your first UE project set up in Perforce!

UE project now being tracked with Perforce showing a pop-up with details of tracking one of the files

Setting up Perforce clients

Now, one needs to be a bit careful since the Server hostname are not typically being resolved by DNS. On the client machine (that’s not the server), start a Command Prompt and type ping P-Server.local and hit Enter. If you get an error, stop here and figure it out. There is no way this is going to work if you can not ping the server.

Confirm client can ping the server.

On Linux/macOS, start Terminal and type ping P-Server.local to confirm the client can find the server. If there are errors, stop here and figure it out.

On Linux/macOS, in the Terminal, type ping P-Server.local to confirm the client can see the server, type control-C to stop

Now we will install P4V on the client machine. Follow the section Installing P4V above to install (only have to install once per each client machine, of course).

We will setup P4V on a macOS machine for variety. Start up P4V and since this is a new install you will get an Open Connection dialog. Ensure Server is set to P-Server.local:1666 and select a User (you can use the Browse... button to find users defined on the server). Click OK.

Ensure the Server and User fields are correctly filled out

We now need to create a Workspace for this user and client for our UE project. On the left, click the Workspace tab and under the drop-down menu select New Workspace...

Select Workspace tab on left and then select New Workspace… on the drop-down menu

Select Browse... to the right of Workspace root

Select Browse… to the right of Workspace root

Navigate to the parent folder where you want to store the local working copy of the UE project. Then click New Folder and type in <user>_<client machine>_<project> (for us this would be parker_mbpm1_Vivaldi). Once created, select it and click Open.

Navigate to a parent folder to store a local working copy of the UE project then press New Folder and type in parker_mbpm1_Vivaldi

Ensure that only the depots that have the desired UE project have a green check mark. For all other depots, right click and select Clear (otherwise click View workspace mapping as text and delete all lines that have the incorrect depot).

Ensure only the the depot that has the desired UE project has a green checkmark, otherwise right-click and select Clear

Click the Advanced tab on top and select Rmdir option and for the On submit drop down menu select Don't submit unchanged files. Click OK.

Under Advanced tab, select Rmdir and Don’t submit unchanged files for On submit

Under the Workspace tab on the left, select the Workspace root and then click Get Latest on top.

Select the new Workspace root under Workspace tab on the left and then click Get Latest

This will fetch a working copy of the UE project into the Workspace root. It may take awhile, simply wait until it is finished.

Fetching a working copy of the UE project to the local machine

Once the working copy is fetched from the server, in the Finder (or Windows Explorer on Windows), navigate to the Workspace root and double-click the UE project to start UE.

Navigate to the Workspace root and double-click the *.uproject file to start UE

Once UE starts, on the bottom right, there is a pop-up menu for Source Control which should be showing disabled.

In UE5, Source Control pop-up in the lower right (on UE4, there is a large button on top for Source Control)

Click on the Source Control pop-up menu and select Connect to Source Control...(or, equivalently, from the Tools menu select Change Source Control Settings...)

Click on Source Control drop-down and select Connect to Source Control…

In the resulting dialog box, select Perforce for Provider, type in P-Server.local:1666 for Server, type in the user name and for Workspace either type in the Workspace name or from the Available Workspaces, select the relevant Workspace. Click Accept Settings

Populate Provider, Server, User Name and Workspace fields

You will then see, on the lower right that Source Control is now in effect.

UE project now under source control

You need to repeat this section for each client machine, user and UE project.

Add a Comment

Your email address will not be published. Required fields are marked *