Unreal Engine 5 with Unreal Game Sync setup guide
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.
- https://docs.unrealengine.com/4.26/en-US/ProductionPipelines/DeployingTheEngine/UnrealGameSync/Reference/
- https://ikrima.dev/ue4guide/source-control/perforce-source-version-control-setup/ - misc notes on setting up server
- https://dev.epicgames.com/community/learning/tutorials/Gxoj/unreal-engine-using-and-setting-up-perforce-repository
- https://allarsblog.com/2017/04/05/populating-perforce-with-an-unreal-engine-source-build/
- https://youtu.be/xuEXqZ0nE70