Using Perforce with Unreal Engine

Guide for using Perforce source control with Unreal Engine.

Windows
MacOS
Linux

Unreal Engine is provided through a Perforce depot that licensees must connect to in order to download the engine. Since Unreal Engine is updated regularly, as a licensee working on a project, you may choose to update your version of the engine to a newer version at one or more times during the development cycle. From the outset, it's important to accurately set up Perforce so that it can sync and integrate engine builds.

Epic sets aside the 2nd and 4th Sunday of the month from 8am-12pm EST (12pm-4pm UT) for performing scheduled maintenance.

Our maintenance schedule may impact our support outlets, including network and server resources, so please plan accordingly.

Required Step

Before continuing, make sure that your company enters into a custom licensing agreement with Epic Games. After entering into a license agreement with us, our support staff will set up your account and contact your company with information that gets you started with our services. And depending on whether you are a game or enterprise developer, you will have different ways of gaining access to Epic's Perforce proxy server.

A sample process overview of upgrading your engine version to a new engine release includes:

Game Developer

If you are a game developer requiring access Epic's Perforce proxy server, you need login credentials, which we will provide to your team's technical contact in their UDN welcome email.

Enterprise Developer

By default, enterprise developers do not get Perforce access, but if they reach out to their Sales Manager, they can request to gain access to Epic's Perforce proxy server. After the Sales Manager sends a Perforce access request to our support team, we will set up their Perforce account, and provide login credentials and onboarding documentation to the enterprise developer's technical contact.

Connecting to Epic's Depot

The first step to being able to connect to Epic's public Perforce depot is to set up a secure Virtual Private Network (VPN) connection to Epic Games. This requires installing Cisco's VPN client (either manually or through an automated web-based process) and signing in using your VPN/Perforce credentials. An overview of the process for creating a VPN connection is provided below:

Web-based Connection

  1. Go to https://vpn.epicgames.com  in your web browser.

  2. Log in using your VPN credentials provided by your technical contact.

  3. Follow on-screen instructions and prompts as needed.

  4. The VPN client is installed and the connection is established.

Manual Connection

  1. Download the Cisco AnyConnect Secure Mobility Client v4.x from: AnyConnect Secure Mobility Client v4.x Download .

  2. Install the client and run it.

  3. Set vpn.epicgames.com as the address to connect to.

  4. Log in using your VPN credentials provided by your technical contact.

  5. The connection is established.

The complete process for setting up and establishing a VPN connection to Epic Games private network is detailed on the Setting up a VPN Connection  page.

Once this VPN connection is established, you will be able to access the depot securely from your location using the Perforce client. The client needs to be installed and configured properly to connect. An overview of the process for installing and connecting with the Helix Visual Client (also known as "P4V") is provided below:

  1. Download the client from the Perforce Software Download Page .

  2. Install the client and run it.

  3. Fill in the appropriate ServerUser, and Workspace info in the Connection Dialog and press OK.

  4. The client opens and connects to Epic's public Perforce depot.

The complete process for setting up the Perforce client to connect to Epic's Perforce depot is detailed on the Setting Up Perforce Connection  page.

Syncing from Streams

Epic hosts a variety of Perforce streams that you can use to sync to our code. Every development team has one "dev" stream, which provides the most recent code from those teams, and our Quality Assurance (QA) department regularly tests "dev" streams before copying up to the "main" engine stream. Snapshots of the "main" stream are copied into "release" streams periodically for heavy QA testing and bug-fixing, leading up to an official release. Following a full release, preview release, or hotfix, a snapshot of the "release" stream is used to migrate fixes back to the "main" stream. When syncing, it is useful to consider what code you need (for example, do you need the whole engine, just a specific stream, or a cherry-picked feature or fix?), how up-to-date you want the code to be, and what level of stability you require.

The following table describes the four types of streams, provides example stream names, and describes the content, relative age, and stability of each stream type:

Stream Type

Example Stream Names

Description

Main

//UE4/Main

//UE4/Dev-Main

Code in this stream is relatively up-to-date, and has passed through some testing. The "Dev-Main" variant is a virtual stream that excludes some samples. Development streams copy up to, and merge down from, this stream.

Development

//UE4/Dev-Core

//UE4/Dev-Rendering

//UE4/Dev-Framework

The source for the most up-to-date work on features relating to a specific area of the engine is the development stream for the team who works on that feature. This code is actively in development and is therefore the least stable type of stream.

Release

//UE4/Release-4.17.0

//UE4/Release-4.19.2

//UE4/Release-Latest

These streams correspond to Epic's official public releases, and are heavily tested and considered very stable. They will contain the latest revision of the named engine version.

The "Release-Latest" stream is virtual and always points to the most recent official release that Epic has shipped. Other than "Release-Latest", these streams can be recognized by their three-part version numbers (such as "Release-4.17.0").

Release Stabilization

//UE4/Release-4.17

//UE4/Release-4.19

When Epic is preparing to release a new version of Unreal Engine 4, a stream will be created from a current snapshot of the main stream. This stream will undergo daily testing and bug-fixing leading up to its public release, so it may be unstable.

They can be distinguished from "Release" streams by their two-part version numbers (such as "Release-4.17").

Syncing to this type of stream is not recommended.

Stream Workflow

The following flowchart illustrates the flow of Engine code and content through the various types of Perforce streams during development and leading into release:

PerforceStreams.png

Integrating, Merging, and Branching

During a game's production cycle, your team may decide to periodically update the project to newer versions of the engine that might include new features or bug fixes. The process for getting an updated build from Perforce is the same as the one you use for the initial sync. However, there is a lot to consider as far as how you maintain the engine on your own Perforce server and how that affects your ability to integrate and merge new builds into your code base while minimizing conflicts.

Merge and Integrate

We recommend a branch hierarchy similar to this:

Branch

Description

//depot/Epic

Contains a pristine copy of Epic's codebase, with no modifications.

//depot/MergeTest

Staging area for merging Epic changes with your own engine changes.

//depot/Dev

After merging the engine release build with your code base and passing integration tests, this is the development tree that you will work from.

Upgrade to a New Engine Release

After getting Perforce access from our support team, you can get the contents of an Engine Release build from Epic, and a good way to get a new build is to:

  1. Sync a copy of the latest Engine release from Epic's Perforce server.

  2. Sync a copy of the //depot/Epic branch from your own Perforce server.

  3. Delete the files from your local //depot/Epic workspace, and copy over the files from the new engine release.

  4. Make a changelist (CL) representing Epic's updates by using P4V's Reconcile Offline Work feature.

  5. After completing your reconcile operations, go ahead and check-in the CL you just made.

    At this point, the Epic branch is a copy of the Engine Release build, which includes integration history, giving the merge tool change information that helps you reduce conflicts while merging and integrating the latest engine updates into your code base.

  6. Merge your latest development branch (//depot/Dev) into the merge/test branch (//depot/MergeTest).

  7. Merge the latest engine release into the merge/test branch (//depot/MergeTest), and test the changes.

  8. Merge the updated version of your game from the merge/test branch (//depot/MergeTest) into the development branch (//depot/Dev).

Here is a diagram showing the expected flow of changes between branches as new engine versions are released:

Perforce_IntegratingMergingBranching.png

The more frequently you update, the less likely you are to run into serious conflicts when merging.

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback