This document provides an elementary description of the plugin and an overview of its capabilities. It assumes that the plugin is already installed on your TeamCity instance.
The plugin looks for the following files and directories on build agent machines to detect existing Unreal Engine installations (both installed from the Epic Games Launcher and built from the source code):
- The
LauncherInstalled.dat
file. Typically located at:- Windows —
{ProgramData}\Epic\UnrealEngineLauncher\
- MacOS —
{home}/Library/Application Support/Epic/UnrealEngineLauncher/
- Linux —
{home}/.config/Epic/UnrealEngineLauncher/
- Windows —
- The
Install.ini
file. Typically located at:- Linux —
{home}/.config/Epic/UnrealEngine/
- MacOS —
{home}/Library/Application Support/Epic/UnrealEngine/
- Linux —
- The
SOFTWARE\Epic Games\Unreal Engine\Builds
registry key (Windows)
Once an engine is detected, its identifier and path are written to corresponding agent properties. TeamCity utilizes these properties to match compatible agents with build configurations that manage UE solutions.
The plugin supports two build graph execution models:
- Single machine
- Distributed
When in distributed mode, your build will be split across all of the available agents based on the description in your BuildGraph XML file: every agent will become a separate build configuration, and each node will become a build step.
Currently, there are a few settings that you should be aware of:
-
Agent types are converted into the agent requirements, and you're free to mark your agents however you like.
For example, suppose your agent definition in the build graph XML looks like this
<Agent Name="Do something dope" Type="Foo;Bar"> ... <Agent>
So, in order to make an agent eligible to run this build you should mark it via declaring custom agent configuration parameter with the name
unreal-engine.build-graph.agent.type
. It might look like thisunreal-engine.build-graph.agent.type = Foo
or you could list as many types as you want like this
unreal-engine.build-graph.agent.type = Foo;Bar;Baz
As long as the agent has at least one matching type it will be eligible to run the build.
-
When distributing a build it usually makes sense to set up a proper shared storage. Currently, you have to specify network share in the similar fashion via declaring another agent property with the name
unreal-engine.build-graph.agent.shared-dir
for each of the agents participating in a build process.
As mentioned earlier, when in distributed mode, the build graph will be converted from one representation (Epic's JSON file, generated by running the BuildGraph command with the -Export parameter) to another (TeamCity's build chain). Snapshot dependencies within the chain will be configured based on how you set them up between nodes in the graph. It's worth mentioning that the resulting build configurations will include all the dependencies of their respective nodes.
It's better to demonstrate with an example. Suppose we have the following part of the BuildGraph description (unimportant details are omitted):
<Agent Name="Work A">
<Node Name="Step A.1">
...
</Node>
<Node Name="Step A.2">
...
</Node>
</Agent>
<Agent Name="Work B">
<Node Name="Step B.1" Requires="Step A.1">
...
</Node>
</Agent>
This will result in 2 build configurations:
- Work A
- Step A.1
- Step A.2
- Work B
- Step B.1
The build configuration "Work B" will depend on a build configuration "Work A" despite the fact it might already have been run after completing step "Step A.1". This is due to the nature of snapshot dependencies and the limitation in TeamCity where triggering another build after completing a build step is impossible. Keep that in mind when writing your scripts.
The integration allows you to notify the UGS (Unreal Game Sync) metadata server about the result of a build using badges. As the build progresses, the plugin will post the corresponding information to the metadata server, from which UGS will eventually retrieve it. For more detailed information about UGS, please refer to the official documentation.
One thing to keep in mind: currently, the endpoints provided by the UGS metadata server are not secured with authorization. Presumably, it's supposed to run within a closed network.
The integration is implemented in two forms:
- As an extension to the Commit Status Publisher.
- As a feature for the "distributed" BuildGraph run mode.
The behavior is similar to other publishers: you need to select the corresponding one and fill out the required parameters.
You can also configure it from Kotlin DSL:
commitStatusPublisher {
publisher = ugsMetadataServer {
serverUrl = "http://localhost:3000"
badge = "Foo Badge"
project = "//foo/bar/project"
}
}
To enable support within a BuildGraph build, you should run it in “distributed” mode and configure the settings as follows:
unrealEngine {
command = buildGraph {
// irrelevant settings are omitted
executionMode = distributed {
badges = enableBadges {
metadataServer = "http://localhost:3000"
}
}
}
}
Alternatively, you can configure it in the UI:
In this case all the badges defined in the script will be published according to the dependent nodes they are linked to.
As an example of the script:
<BuildGraph >
...
<Agent Name="Build A" Type="A">
<Node Name="Node A.1">
...
</Node>
<Node Name="Node A.2">
...
</Node>
</Agent>
<Agent Name="Build B" Type="B">
<Node Name="Node B.1">
...
</Node>
<Node Name="Node B.2">
...
</Node>
</Agent>
<Badge Name="Foo Badge" Project="//foo/bar/project" Requires="Node A.2;Node B.1"/>
...
</BuildGraph>
Here, the badge "Foo Badge" tracks the execution of two nodes: "Node A.2" and "Node B.1". As soon as one of them starts executing, the badge will update its status. If one of them fails, the status will change to "Failure". The badge will only show "Success" when all dependencies complete successfully.
- Currently, for the distributed BuildGraph mode to work, your build configuration must contain exactly one active build step. This should be addressed in TW-89015
If you'd like to learn more about the plugin, check out these blog posts: