How to Configure Helix Core + Game Engine

Purpose of the TypeMap

Your TypeMap is a server-wide setting that determines how files are handled by the server. Your TypeMap only affects files added to the server after it was set up, so it is very important to set it up first.

Default TypeMap Settings

By default, Helix Core will attempt to auto-detect if certain files should be stored as text or binary data.

By default, Helix Core will set all of your workspace files to read-only until you check them out. Any files set to always writable (+w) will not be set to read-only. This is useful for files that are changed automatically, rather than being checked out by a user.
 

Examples of Common TypeMap Modifiers

There are several different types of modifiers, but these three are the most commonly used:

 +l automatically lock a file so multiple users don’t edit it at the same time. (This is very important for game engine binary files, which can’t be merged.)

 +w always allow this file to be written.

 +S tells Helix Core to only store the latest revision and not the entire history of revisions, saving space on your server. This is useful for large intermediate files that can be recreated if needed, such as baked lighting, shaders, or built executables. (You can also put a number after the S to specify a certain number of revisions to save.)

You can get more information about file types and many more file type modifiers in the Helix Core Command-Line Reference.

Edit the TypeMap

To edit the TypeMap, we need to open our terminal window or cmd prompt and use the command-line client, p4.

1. In the new command line prompt, type the following and click enter: p4 typemap
   
   A text editor should load with a file.
   
   (Note: This text file must open in its own window. If you immediately get a message saying typemap not saved, be sure to close all instances of your text editor and run the command again.)
2. Underneath the line that says TypeMap:, indent and then add lines for each file extension and/or path you want to specify. On each line, you specify the file type and/or modifiers and then the pattern to match.
   
   Patterns all start with // and then the server path and file extension.
   
   Use ... as a wildcard to match any number of characters in any sub-folders. Use * as a wildcard to match any number of characters but no sub-folders.
   
   This example does three things:
   1. Treat all .meta files as binary, regardless of their actual contents.
   2. Treat all .exe files as binary, keep them always writeable, and only store the latest revision on the server.
   3. Automatically lock any .obj files in the project_a depot (but no others) and let Helix Core determine their type automatically.

TypeMap:
    binary //....meta
    binary+wS //....exe
    +l //project_a/....obj

We have some example TypeMap files below that you can copy and paste into your TypeMap to get started or you can customize them to your needs. Be sure you read through these examples and make sure you understand what they do.

Save the TypeMap file and close the text editor.
You should see typemap saved in the terminal window.
 

Unreal Engine Example TypeMap

Typemap:
    binary+w //....exe
    binary+w //....dll
    binary+w //....lib
    binary+w //....app
    binary+w //....dylib
    binary+w //....stub
    binary+w //....ipa
    binary+l //....uasset
    binary+l //....umap
    binary+l //....upk
    binary+l //....udk
    binary+l //....ubulk
    binary+wS //..._BuiltData.uasset

Unity 3D Example TypeMap

Typemap:
    text+l //....cm
    text+l //....proc
    binary+l //....prefab
    binary+l //....mat
    binary+l //....unity
    binary+l //....asset
    binary+lS //....dds
    binary+lS //....bnk
    binary+lS //....light
    binary+lS //....shadow
    binary+lS //....ibl
    binary+lS //....bik
    binary+lS //....upk

Now that your server knows how to handle different file types, we are ready to create our first stream and workspace.

What Is Perforce Streams?

The purpose of Perforce Streams is to allow certain users to collaborate on files, sharing those through Helix Core without affecting users in other streams.

A streams depot uses “Streams” to organize the different branches of your project. For a small team, you may just use one main stream, but as you grow, you will likely create multiple streams branching off from that main one.
 

Streams Example

For example, you may have your artists working in an art stream while your developers are working on some complicated automation in a development stream.

Your artists won’t be distracted by the development work while it is in progress because the two streams are using separate versions of the files. Once the development work is stable and ready for the artists to use, then you can copy/merge the files from the development stream into the art stream and the artists will now see those changes.

Create the Main Stream

For now, let’s keep it simple and create a main stream called "main" so we can put our files in it and begin working.

1. In P4V, go to the Stream Graph tab on the right.
   If you don’t see it, you can open the Stream Graph through View menu or by clicking on the + icon to the left of the other tabs (or pressing Alt + 7).
2. Make sure your project’s depot is selected in the Depot: dropdown menu.
3. Right click in an empty space in the Stream Graph on the right side and select New Stream…. (Or press Ctrl + N)
4. Fill out the stream info:
   1. Give your stream a simple name (e.g. main)
   2. Make sure the Stream Type is set to mainline
   3. Double check the Depot: is set correctly.
   4. (Optional) Add a description of the stream.
   5. UNCHECK the Create Workspace and Populate options at the bottom. We will do this manually next.
5. Click OK, and you will now see your new stream in the Stream Graph.

In order to work on files in Helix Core, you need to create a workspace. A workspace is a folder on your local machine that is linked to files on the server.

Using this workspace, you can add new files to the server, edit existing files, get the latest changes from others, or go back to previous versions of files.

1. Right click on the stream you just created and select New Workspace…
2. Fill out the basic options:
   1. By default the workspace will be named using the following pattern: <Username>_<Machine_Name>_<Stream_Name>_<Number>
      You can change the workspace name to whatever you want but it is usually best to at least include your username and the project name so you can easily identify the workspace later.
   2. The Workspace root is the folder on your local machine that will be linked to the files on the server. Put this wherever you like, but it is recommended to name the folder the same as your workspace name.
   3. The Stream is already set to the one we selected and it automatically fills in the Workspace Mappings.
   4. Check the Switch to New Workspace and Automatically get all revisions options at the bottom.
3. (Optionally) Go to the Advanced tab at the top where we can set a few more helpful options:
   1. You can add a description of the workspace if you like.
   2. Under File Options: you can read about the options you can select. For example, to keep your workspace folder clean, you can select the Rmdir option so that empty folders will be removed.
   3. For On Submit it is generally a good idea to change from Submit all selected files to Don’t submit unchanged files so that you don’t waste time and space uploading new versions of files that haven’t changed. 
   4. Except in specific circumstances, a workspace should only be used by one user on one computer. To prevent other users from trying to edit and use your workspace, which could cause problems, you can check the “Locked: only the owner can edit workspace settings” checkbox above the Description field.
4. Click OK and you will see your new workspace on the left half of p4v, under the Workspace tab.

Set Up Helix Core to Ignore Files

By default, Helix Core wants to version all of your files. But for game engine builds, you need Helix Core to ignore some of the files, such as individual user settings, caches, and others. Use the following instructions to create the ignore file, set up Helix Core to ignore files, and then submit the ignore file.

In order to use an ignore file, we need to tell our local Helix Core client where to look for an ignore file. This is done by setting the P4IGNORE environment variable or by using the p4 set command. (Note: if both exist, environment variables take precedence over p4 set variables.)

For this example, let’s decide to call our ignore files .p4ignore by opening a terminal or command prompt and typing the following:

p4 set P4IGNORE=.p4ignore

You can enter p4 set on its own to see all variables set in your environment and where they are set.

Note, each user needs to run this command to set their P4IGNORE variable unless your system admin has already set that Environment Variable for them on their machine.

Create the Ignore File

Now that Helix Core knows to look for a file called .p4ignore in the workspace, we can create the ignore file.

1. To create a .p4ignore file, open up your notepad and save a blank file with name .p4ignore inside your workspace root folder. For example:
   C:\Users\YourName\Perforce\Yourname_Workspace\.p4ignore
   Note: There should not be a .txt extension on this file because we set P4IGNORE to just .p4ignore. If you want to use a .txt extension, you can use p4 set P4IGNORE=.p4ignore.txt or any other name you want.
2. In your text editor, write one line for each file path you want ignored.
   1. Paths are case-sensitive.
   2. * can be used as a wildcard to match any number of characters.
   3. Putting a / at the end of a path will only match directories. Otherwise it will match any files OR directories with the same characters.
   4. A ! at the beginning of a line will make sure that matches files are not ignored, even if a previous rule matches them.
      
      For a more complete explanation, see the P4IGNORE Documentation.
      We have examples for Unreal and Unity below that you can copy and paste into your .p4ignore file as a starting place. Be sure you understand what is being ignored so you don’t accidentally ignore something you don’t want to (or you accidentally ignore something you should be storing in your depot).
      Remember, Helix Core is case-sensitive, so double check your paths to make sure you are using consistent cases.
3. Save the file and then test it out. You can either try to add a file in P4V that should be ignored, in which case you will get a popup telling you the file is ignored, or you can use the p4 ignores command in the terminal.
   In the terminal, type:

   p4 ignores -i -v the_path_to_the_file_you_want_to_check

   
   The output will tell you if the file was ignored or not and will tell you which line in the ignore file is the one that matched. This is incredibly useful for testing things out because the file paths you enter in the terminal don’t even have to exist. You can just test out any hypothetical path to check if they would be ignored or not.
4. Back in P4V, click on the .p4ignore file in the workspace, then click on Add at the top of the window (or right click on the file and select Mark for Add). This will add the file to the default changelist.
5. With the file selected, click on Submit at the top of the window (or right click on the file and select Submit…)
6. Write a description for your changelist, such as “Added ignore file” and then click Submit.

Now your ignore file is saved in the depot so that other users will have the same ignore file in their workspaces.

Unreal Engine Ignore File Example

# User-specific folders or temporary files that should not be versioned.
    Saved/
    Intermediate/
    DerivedDataCache/
    FileOpenOrder/
    obj/
# Certain file types that should not be versioned.
    *.pdb
    *-Debug.*
# Visual Studio user settings files that should be ignored.
    .vs/

Unity 3D Ignore File Example

# Unity Files and Folders to ignore
    Library/
    Temp/
    Obj/
    Build/
    Builds/
    UserSettings/
    MemoryCaptures/
    Logs/
    Assets/AssetStoreTools/
    Assets/AddressableAssetsData/*/*.bin*
    Assets/StreamingAssets/aa.meta
    .collabignore
# Build files to ignore
    *.apk
    *.unitypackage
# Gradle cache directory
    .gradle
# Autogenerated project files
    /Assets/Plugins/Editor/JetBrains*
    .vs
    ExportedObj/
    .consulo
    *.csproj
    *.unityproj
    *.suo
    *.tmp
    *.user
    *.userprefs
    *.pidb
    *.booproj
    *.svd
    *.pdb
    *.mdb
    *.opendb
    *.VC.db
# Unity3D generated meta files
    *.pidb.meta
    *.pdb.meta
    *.mdb.meta

Now that we have set up our server to properly recognize file types and ignore files, we can add the project files to the workspace.

1. Copy your game engine project files into your workspace root folder.
2. In P4V, click the Refresh button in the upper left so you can see all the files in your workspace.
3. Add all the files to the default changelist by selecting them all in the Workspace tab and then click Add at the top of the window.
   
   Alternatively, you can right-click on your top-level folder inside the Workspace tab and select Reconcile Offline Work…, which will look through all the subfolders for any files that have been changed or have not yet been added and put them in the default changelist.
   
   This may take a little while if you have a lot of files in your workspace.
4. Go to the Pending tab on the right to see your pending changelists. Right now that should just include the default changelist.
   
   If you don’t see that tab, you can open it from the View menu or the + icon to the left of the tabs.
5. With your changelist selected, click Submit at the top of the window (or right-click on the changelist and select Submit…)
   
   
   The first time you submit a game engine project it may take a while to upload all of the files to your server, depending on your network connection. Once you have submitted the initial project files, future submits will only include files that have been changed or added since the last submit, which will generally be much fewer than this initial commit.

Congratulations! Now your files are stored in the depot on your server and you can start working on them.

Submit Changes with Changelist Descriptions

As you and your colleagues work on your project, you will want to regularly submit your changes along with changelist descriptions so that everyone has the latest versions of each others’ files and you maintain a history of who made which changes.

You can either do that in P4V by first selecting the files you want to change and clicking Checkout, making your changes in the engine, and then Submitting your changelist when you are ready, OR you can use the Version Control menu built into Unreal Engine to make this process more streamlined. The files are submitted to your server the same either way.

Source Control Extension in Unreal Engine

Unreal Engine comes with a built-in source control extension that integrates with Perforce. In UE4, this is located in the upper left area of the screen, and in UE5, it is located in the bottom right. It can also be accessed through the Tools menu.
 

1. Click on the Source Control icon and select Connect to Source Control
2. Select Perforce as your provider.
3. Fill in your server information like we did in P4V.
4. Enter your username.
5. Enter your workspace name or select it from the Available Workspaces dropdown.
   Note: Be sure you select the workspace that contains the project you have open, otherwise it will not recognize your changes. If you copied your file from a different location, the one in your Recent Projects list may not be the one you want.

The Source Control icon will change to show you are connected.

Now, whenever you make changes to your project files, Unreal will display a popup message asking if you want to checkout the files. You will want to check out any files before saving your changes. Then, when you are ready to submit them, you can click on the Source Control icon and select Submit To Source Control.

From the Source Control menu, you can also get the latest changes from other users.

Accessing Source Control Menu on Individual Assets

In addition to submitting your changes and getting the latest changes, you can also access the source control menu on individual assets by right-clicking in the Content Browser. This will allow you to do things like compare your changes with what is currently on the server, revert your changes to undo them, view the history of changes on that file, and more.
 

Automatically Check Out Files

Finally, in the Source Control section of the Editor Preferences (Under General - Loading and Saving) you can set it to automatically check out files when you modify them, so you don’t need to click to check them out every time. Just be careful to revert them if you didn’t mean to check them out so that other users can still edit them.

Submit Changes with Changelist Descriptions

As you and your colleagues work on your project, you will want to regularly submit your changes along with changelist descriptions so that everyone has the latest versions of each others’ files and you maintain a history of who made which changes.

You can either do that in P4V by first selecting the files you want to change and clicking Checkout, making your changes in the engine, and then Submitting your changelist when you are ready OR you can use the Version Control menu built into Unity 3D to make this process more streamlined. The files are submitted to your server the same either way.

1. Open the Unity project inside your workspace and go to Edit > Project Settings and select the Editor category.
2. Under Version Control, select Perforce as the Mode
3. Fill in your username, password, your workspace name, and your server address (including ssl, if your server has it, and port number, which defaults to 1666)
4. Look at the remaining settings and select which ones you want, such as Automatic Add and if you want Overlay Icons. For more information on these settings, see the Unity documentation.

Now, in your project tab you can right-click on any asset to access the Version Control options, such as Check Out, Get Latest, Submit, Revert, and more. Some of these options will also show up in the upper right corner of the Inspector tab for each asset.
 

Unity will also automatically check out files when you modify and save them, making sure you don't forget.

Submitting Multiple Assets At A Time

In order to submit multiple assets at once, you can open the Version Control window by going to Window > Asset Management > Version Control. From here, you can see the assets that are checked out in any changelists and you can submit the entire changelist from there, rather than submitting each asset individually.