Unreal Engine 5 with Unreal Game Sync setup guide

Posted on Jun 25, 2023

Helix Core - Perforce server

To install helix core server please follow instructions provided at the official product web page.

What’s worth mentioning here is that upon my tests I discovered that for an unknown to me reason the helix core server is very laggy and has very long response times when it’s installed on Windows and is being accessed from a remote client. Actions like p4 info takes about 5 seconds to print results rather than doing that instantly. I have also tried installing it on WSL which helped a little bit but the response for the same command was about 3 seconds. Due to this I highly recommend installing it on Linux server.

TypeMap

Once helix core server is up and running this is the typemap I’m using for Unreal Engine based depots:

	binary+l //....uasset
	binary+l //....umap
	binary+w //....3ds
	binary+w //....abc
	binary+w //....ai
	binary+w //....aiff
	binary+w //....blend
	binary+w //....bgeo
	binary+w //....bmp
	binary+w //....dae
	binary+w //....dds
	binary+w //....dxf
	binary+w //....exr
	binary+w //....fbx
	binary+w //....flac
	binary+w //....geo
	binary+w //....gif
	binary+w //....glb
	binary+w //....gltf
	binary+w //....hip
	binary+w //....hipnc
	binary+w //....hmv
	binary+w //....jpg
	binary+w //....jpeg
	binary+w //....ma
	binary+w //....mb
	binary+w //....mp3
	binary+w //....mp4
	binary+w //....obj
	binary+w //....ogg
	binary+w //....pic
	binary+w //....picnc
	binary+w //....png
	binary+w //....psb
	binary+w //....psd
	binary+w //....sbsar
	binary+w //....skp
	binary+w //....spp
	binary+w //....tga
	binary+w //....tif
	binary+w //....tiff
	binary+w //....usd
	binary+w //....wav
	binary+w //....wmv
	binary+w //....vfl
	binary+w //....zpr
	binary+w //....ztl
	binary+w //....exe
	binary+w //....lib
	binary+w //....app
	binary+w //....dylib
	binary+w //....stub
	binary+w //....ipa
	binary+Sw //....dll
	binary+Sw //....pdb
	text //....c
	text //....config
	text //....cpp
	text //....cs
	text //....h
	text //....ini
	text //....m
	text //....mm
	text //....py
	text //....txt
	text+w //....DotSettings
	text+w //....modules
	text+w //....target
	text+w //....version

Note that this is setting the typemap globally to the entire server. If you only want to apply them locally to a depot, insert the depot name after the // e.g. text+w //GameName/....cpp.

Unreal Engine source

Go to Unreal’s GitHub and download the source code for the engine. Put it inside your workspace. Run Setup.bat file to download all the dependencies required to run the engine. I found out that perforce doesn’t really deal well with such huge changelists (around 250k files for version 5.2) so I recommend to start submitting the files directory by directory rather than everything at once. Otherwise P4V becomes stale and you can’t really interact with it and even when you try to submit something using command line it sometimes just get stucks and you have to redo everything from scratch. This part was very annoying to me especially given Perforce advertises itself as an ideal source control to deal with big amount of big files…

Note that due to this point I haven’t generated project files nor have I run the engine build. This is on purpose as we DO NOT want to submit ANY engine/game specific binaries to the depot. I will explain why in the next steps.

Note2, I have not set up any P4IGNORE to this point on purpose as there is .p4ignore file somewhere in the engine source code that actually excludes some binaries that are required to successfully build the engine. Also, as said above, this is also reason why I have not generated any project files etc. to avoid subitting ANY temporary files by accident.

Building UGS

Now that the engine is submitted to your depot it’s time to build Unreal Game Sync program. Go to Engine\Source\Programs\UnrealGameSync directory and open the UnrealGameSync.sln file. Once opened change the program build from Debug/Development to Release and build UnrealGameSync and Installer projects.

Now inside the UnrealGameSync\Installer\bin\Release directory you should be able to find UnrealGameSync.msi which you should use to install the UnrealGameSync on your computer. This is the installer you want to distribute to all members of your team as well so they can install it too without building it.

Now create new stream in your depot, you can call it whatever you want, in my case it’s UnrealGameSync. Switch to the new stream. Once the new stream is active create Release directory and inside it, paste everything from UnrealGameSync\UnrealGameSync\bin\Release\netcoreapp3.1 directory. This is very important as we will need to point UGS to a binaries it should be using. Once copied submit them to the new stream.

Now you can open the UnrealGameSync app and fill in the required data with server ip and username. For the depot path please point it to the depot that contains binaries we submitted in the previous step. If your depot name is foo and your stream name is UnrealGameSync it should look like //foo/UnrealGameSync/. Once you press Ok it should ask for the password for your user.

After that you should see the main UGS window and prompt to open new project. Select Workspace project and point it to your perforce workspace and .uproject file and press Ok. You will now see the history of your project with ability to sync to arbitrary change list.

Precompiled binaries

First step to get precompiled binaries is to add Build folder inside your game’s root directory (right next to your project’s .uproject file). Inside this file we need UnrealGameSync.ini file. Inside it you will need to specify two things:

Depot path to your .uproject file
Depot path for your editor zipped binaries. This is how it could look like:

[//foo/Main/YourGameName/YourGameName.uproject]
ZippedBinariesPath=//foo/Dev-Binaries/++foo+Main-YourGameNameEditor.zip

Note that there is //foo/Dev-Binaries stream used. This is the third and the last stream we need and it’s used to store the zipped binaries for the editor.

Once you have this file, from the root directory of the engine you can run the following command: Engine\Build\BatchFiles\RunUAT.bat BuildGraph -Script=Engine/Build/Graph/Examples/BuildEditorAndTools.xml -Target="Submit To Perforce for UGS" -set:EditorTarget=YourGameNameEditor -set:ArchiveStream=//foo/Dev-Binaries -P4 -Submit Once this command is completed successfully the zipped file will be already on the depot submitted.

If you now go to the Options of the UGS and select Sync Precompiled Binaries it will highlight the change lists that have binaries available for them and allow you to sync to them while also downloading the binaries so you don’t have to build them on your own.

Automation

The above process is very simple to automatization, all what’s required is a CI agent, either Jenkins or TeamCity or any other of your choice. It needs to have a P4 trigger to whenever anything to a pointed depot is submitted. Once a new submit is detected it should run the above script to build new binaries.

Resources

Here is a list of resources that I have encountered while messing with the system that I found useful.