Configuring UnrealGameSync (UE 5.5)

An overview of UnrealGameSync is provided by Epic here: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-game-sync-ugs-for-unreal-engine.

Prerequisites

In order to support UnrealGameSync (UGS) metadata, the stream that Horde is connected to must be the same stream that your UGS users will sync their game content from. This stream should exclude files which are unnecessary for builds such as source art. If this is not compatible with your perforce setup, please contact support@universalfoundry.io.

Update Horde Source to Be Compatible with Universal Foundry Auth

There is a small omission in the stock UE codebase for handling authentication in a standard way which is addressed by this pull request.. We expect this to be included in 5.6 but as of 5.5, you will need to apply this patch to your codebase manually.

Add this line to Engine/Source/Programs/Shared/EpicGames.Horde/HordeHttpAuthHandler.cs:

--- Engine/Source/Programs/Shared/EpicGames.Horde/HordeHttpAuthHandler.cs 2024-11-19 19:44:21.000000000 0000
+++ Engine/Source/Programs/Shared/EpicGames.Horde/HordeHttpAuthHandler.cs 2024-11-19 19:44:21.000000000 0000
@@ -449,6 +449,7 @@
   values[$"Providers:{oidcProvider}:ServerUri"] = authConfig.ServerUrl;
   values[$"Providers:{oidcProvider}:ClientId"] = authConfig.ClientId;
   values[$"Providers:{oidcProvider}:RedirectUri"] = localRedirectUrl;
+  values[$"Providers:{oidcProvider}:Scopes"] = "openid profile email";
   ConfigurationBuilder builder = new();
   builder.AddInMemoryCollection(values);

Submit that change to P4 before continuing to the next step.

Build UnrealGameSync

To use UnrealGameSync, you need to have Horde create two builds for you:

1. The UnrealGameSync installer to be distributed to new team members
2. UnrealGameSync itself will check Horde for new builds of UnrealGameSync. You will need to make this build separately.

Steps to build:

1. Copy the contents of the Universal Foundry BuildGraphs repo to ./UniversalFoundry/. The UniversalFoundry folder should be a sibling of Engine. Add and commit this folder to Perforce.
2. Navigate to Horde: https://horde.app.universalfoundry.io
3. At the top, navigate to your project and stream. For example, if your project is “Lyra” and the stream is “55”, you would click “55” here:
4. Click “Utility”:
5. Click “New Job”:
6. From the Template pulldown, select “Build UnrealGameSync”
7. Click “Start Job”
8. Within the Horde Dashboard, you should see your job queued up. Wait for them to finish and then proceed.

UGS Client Setup

1. From the Universal Foundry Settings page, copy the “Horde API URL” to the clipboard.
2. Download the UGS installer from the Horde Tools page: https://horde.app.universalfoundry.io/tools.
3. Run the installer. When prompted, paste the Horde API URL into the “Server” section of this dialog:
4. Instructions for opening your project, connecting UGS to Perforce, etc are here: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-game-sync-client-setup-for-unreal-engine

Upload Artifacts to Horde

You will need to properly tag and upload your binaries for UGS. If you’re using the BuildEditorAndTools.xml example from Epic, you may already have the necessary code set up.

If not, there are two key parts from that example which you will want to adapt to your use-case.

First is this “Prepare a build for UGS” Node: https://github.com/EpicGames/UnrealEngine/blob/2d53fcab0066b1f16dd956b227720841cad0f6f7/Engine/Build/Graph/Examples/BuildEditorAndTools.xml#L140

<!-- Prepare a build for UGS -->
<Node Name="Stage for UGS" Requires="$(SubmissionDependencies)" Produces="#PublishBinaries">
    <!-- Clear out the staging directory -->
    <Delete Files="$(ArchiveDir)\..."/>
    <!-- Tag AutomationTool build folder recursively -->
    <Tag Files="Engine/Binaries/DotNET/AutomationTool/..." With="#ArchiveBinaries"/>
    <!-- Write a text file marker indicating that we're using precompiled binaries -->
    <Spawn Exe="cmd.exe" Arguments="/C echo. &gt;&quot;$(RootDir)/Engine/Build/PrecompiledBinaries.txt&quot;"/>
    <Tag Files="$(RootDir)/Engine/Build/PrecompiledBinaries.txt" With="#ArchiveFiles"/>
    <!-- Partition all the binaries and symbols -->
    <Tag Files="#OutputFiles" Except=".../Intermediate/..." With="#ArchiveFiles"/>
    <Tag Files="#ArchiveFiles" Except="*.pdb" With="#ArchiveBinaries"/>
    <Tag Files="#ArchiveFiles" Filter="*.pdb" With="#ArchiveSymbols"/>
    <!-- List all the files being archived -->
    <Log Message="Archive binaries:" Files="#ArchiveBinaries"/>
    <Log Message="Archive symbols:" Files="#ArchiveSymbols"/>
    <!-- Stage all the files to be archived -->
    <Copy Files="#ArchiveBinaries" From="$(RootDir)" To="$(ArchiveStagingDir)"/>
    <Strip Files="#ArchiveSymbols" BaseDir="$(RootDir)" OutputDir="$(ArchiveStagingDir)" Platform="Win64"/>
    <Tag Files="$(ArchiveStagingDir)/..." With="#PublishBinaries"/>
</Node>

This Node handles all the copying/tagging.

After that you will want to do something similar to the “Upload binaries to Horde” elements: https://github.com/EpicGames/UnrealEngine/blob/2d53fcab0066b1f16dd956b227720841cad0f6f7/Engine/Build/Graph/Examples/BuildEditorAndTools.xml#L177

   <!-- Upload binaries to Horde -->
   <Property Name="UgsProjectKey" Value=""/>
   <Property Name="UgsProjectKey" Value="ugs-project=$(Branch)/$(UProjectPath)" If="'$(Branch)' != '' and '$(UProjectPath)' != ''"/>
   <Property Name="UgsProjectKey" Value="ugs-project=$(Branch)" If="'$(Branch)' != '' and '$(UgsProjectKey)' == ''"/>
   <Artifact Name="editor" Description="Editor PCBs" Type="ugs-pcb" BasePath="$(ArchiveStagingRelativeDir)" Keys="$(UgsProjectKey)" Metadata="ArchiveType=Editor" Tag="#PublishBinaries"/>

Once you’ve called those steps, UGS will be able to pull Binaries from Horde. The key part here is the Type=“ugs-pcb” which is what UGS looks for when sourcing artifacts.