Version Control lets teams share assets and code with one another. Using version control organizes files across large projects on a server and gives everyone speedy access to them. A history of changes is maintained, so when problems are discovered, you can revert back to the previous version.
For coders, it provides quality and productivity enhancements, such as automating builds of the game. It provides the ability for additions and changes to be reviewed by multiple developers before being incorporated into the game’s primary code base.
Helix Core is the most popular version control system among game developers. It has become popular because it is easy to use, handles large files, is fast and has features that enhance productivity and collaboration. It is great for coders and non-code contributors such as designers and artists.
Unreal Editor has built-in integration to Perforce Helix Core. Epic uses Helix Core for their own development, and they encourage third-party developers using their Unreal Engine to use Helix Core.
We will use Perforce Software, as well as software made by Epic. The Unreal Engine/Unreal Editor integration we are showing here is maintained by Epic Games, and is documented along with other Unreal features. From here on out we’ll refer to Unreal as “UE.”
We are going to look at what it takes to add Helix Core to your workflow. You will learn how to:
- Install Helix Core Server and Clients on Windows
- Set up a Workspace, and explain the difference between Depot and Workspace
- Put a project into a Workspace
- Add project elements to the Depot
- Discuss what folders should be added, and why?
- Check out and Open a (.uasset or .umap) file
- Explain changelists
- Make a change
- Submit a change
Along the way, you’ll see important features such as file locking, a unique feature to Helix Core, which prevents users from overwriting files that others may have open.
This is important because Asset files (with the extensions .uasset and .umap) are the primary files that are modified using the Unreal Editor. These files are binary, so they cannot be opened as text or merged in a text-based merge tool.
When a user is done editing files they have locked, they check in, or submit those files, uploading the changes to the server and releasing the lock on the files.
For some of our examples in this video, we’ll be using P4V, the visual client that comes with Helix Core. It is easy to use and provides access to version control features that aren’t available in UE at this time. Helix Core also has a command line client, which is popular for engineers and coders.
Helix Core and UE both have their own integration with Microsoft Visual Studio, which is popular with game developers. We aren’t going to explore the P4VS integration in this video, but the three systems (UE, Helix Core and Visual Studio) work together seamlessly.
It is a best practice to run Helix Core on a high-performance server (either hardware you have on premises, or in the cloud). This gives team members the availability and performance they need for maximum productivity.
The p4 server, as we call it, can run on a workstation, and this is a great way to get started learning if you are new to Perforce.
It’s easy to install Helix Core. For this demo, we are installing Helix Core Server (p4d), the command line client (p4) and the Visual Client (p4v).
First, let’s visit the downloads page at www.perforce.com/downloads
We are going to select Helix Core (P4D) Server.
The first dropdown, Family, lets you pick the OS. Click on the second dropdown, PLATFORM and choose Windows (x64). We’ll run with the default (latest) version so just click DOWNLOAD.
After this is done, let’s go ahead and pick Visual Client (P4V) from the downloads page, and pick the same choices we made for Family, Platform and the latest version.
Once the download is finished, let’s install the p4d server and command line client. They use the same installer.
After it initializes, you’ll see a choice of what to install.
You won’t need the broker or proxy for this project. They default to unchecked, so just confirm that and click next.
We will use the defaults for the rest of the choices, and proceed until the installation finishes.
Now let’s install P4V, the visual client, by double-clicking its installer.
This installer is used for a number of Helix Core apps. After it initializes, click next and you’ll see the list.
You will want the Admin tool, and P4Merge. You already have the command line client p4, but it won’t hurt to leave that selected here.
Accept the defaults by clicking next.
On the next panel, in the Server field, type in localhost:1666
Skip the username, and choose notepad for the p4 text editor. You can change this later. Hit next, and then hit install.
Now, we will test to see if the server is working by running the P4V client.
If it isn’t already there, enter localhost:1666 into the Server panel.
On the righthand side, next to the user: field, click the New button.
The server is wide open in terms of security right now, so you are allowed to create yourself as the first user.
Fill out all the fields.
Click OK and we’re logged in!
With Helix Core, a “workspace” connects your computer to the server. Files on the server are kept in a “Depot”, which is similar to a “repo” in some other version control systems, but it often holds more than one project.
In daily use, the workspace is basically a folder on your computer that Perforce knows about.
You work on the files locally in your workspace, and then you “sync” or “submit” those files with the server Depot.
Let’s create a new workspace. First, make sure the path exists for your workspace.
Now, go to the View menu, and click on the Workspaces menu item.
This opens the workspace tab. Right click and select New Workspace from the context menu.
Give your new workspace a name. workspace root field, change the path to the folder on your machine you wish to use to contain your “work in progress” files for this project.
I’m naming my workspace to match my project.
Note that you can have multiple workspaces on the computer for different projects, and you can create them as you need them.
Before we move on, we need to make one setting to the Helix Core (p4) server, via the command-line.
Open the command prompt.
We will use the P4 Typemap command to tell Helix Core how to treat Unreal file types.
Setting the typemap will affect how files get set to read only or writable inside of Perforce.
This will open notepad, with the Perforce File Type Mapping Specification.
It should look like this.
Now save the file in Notepad.
The message in the command window should say “Typemap saved”.
Once you have a server and a workspace, you can start putting files under version control, by adding them.
For loading a number of files, it’s better to do this outside of UE, using Perforce tools. This is because additions and changes done in UE are usually made to one file at a time. Using Perforce tools like P4V, you can select a number of files and add them to the server all at one time.
When you create a new project in UE, you can choose whether it incorporates C++ code and Blueprint elements. If you are a coder, and are using C++ code in your project, you will see a Source directory as well. You should initially add only the following directories of your project:
Folders and files highlighted in Green should be added to your depot. The Binaries folder in Yellow is optional, depending on how your team wants to work together. It is not required if every team member is going to compile their editor/game themselves, but should be included in the initial add if there are team members who will only be consumers of the binaries as they create content.
Note that the server typemap we setup before allows coders to compile binaries without them being set to be Read-Only by Helix Core.
Now let’s add files to Helix Core.
We will use P4V in this video, but you can also do this with the commandline client p4.
To add files or folders to the server depot, first select the workspace pane. Select files/folders and then right-click and select the Mark For Add option.
Whenever you perform a version control activity on a file, such as checking it out, editing it, adding a new one, marking a file for deletion, etc., that file will be added to a changelist. A Perforce changelist is a list of files, their revision numbers, and operations to be performed on these files.
There is always a default changelist you can use, but you can also create changelists for specific tasks, such as adding these files.
We will write a description for this change we are making, then click OK.
This will add the files to our change list. Changelists are uniquely numbered.
Changelists appear under the Pending Tab. Click it, and you’ll see your new numbered changelist. Click the arrow and you’ll see the files and folders you just selected for addition to the depot.
Right click on the changelist, and the first menu item you see is “Submit”. You see a confirmation dialog box, where you can change or add to your description. Click Submit. The files will be added to your server depot.
You can confirm this by clicking on the Depot tab, and navigating down the list of files and folders, to find your newly added files.
Once the workspace for the project has been established, you can perform most version control activities from inside UE. Now we will look at how Helix Core is used from inside UE.
Before we start working, let’s make one more setting.
We need to set a couple of environment variables so UE can find your workspace.
Open a command window.
p4 set P4USER=your.username
p4 set P4PORT=localhost:1666
Now, let’s start exploring version control from within UE.
The Source Control Icon is prominent in Unreal Editor.
Click and choose Change Source Control Settings.
If you’ve completed all the steps in this video so far, all you have to do is drop down the Provider menu, and choose Perforce. The server and user should already be filled in.
Just in case they are not setup, you will choose:
- Perforce as the provider
- Locahost:1666 as the server
- In my case, the username is perforce
After confirming or making these choices, click Accept Settings.
When it’s time to work on a file, in the content browser, right click on a folder, choose Check Out
The Source Control section of the menu has Check Out, Mark for Add, Check In and Sync.
To update your workspace with the latest files on the server, choose sync.
We are going to make a small change to the blueprint for Boris.
When the change is done, click Check In.
Then we see the UE Perforce Changelist Dialog Box.
We see a list of the files we’ve changed, and add a quick description of our work.
The change is submitted and the new version is in the depot.
Now we can look at the version history of the file.
And we can even compare the changes we’ve made from within the Unreal Editor.
This has been a quick tour of Unreal and Helix Core integration.
Not a Helix Core Customer? We can help you ship better products, faster.