Using Gradle to build and version a UE4 project

Automated builds are a pretty important tool in a game developer's toolbox. If you're only testing your Unreal-based game in the editor (even in standalone mode), you're in for a rude awakening when new bugs pop up in a shipping build that you've never encountered before. You also don't want to manually package your game from the editor every time you want to test said shipping build, or to distribute it to your testers (or Steam for that matter).

Unreal already provides a pretty robust build system, and it's very easy to use it in combination with build automation tools. My build system of choice is Gradle, since I use it pretty extensively in my backend Java and Scala work. It's pretty easy to learn, runs everywhere, and gives you a lot of powerful functionality right out of the gate. This won't be a Gradle tutorial necessarily, so you can familiarize yourself with how Gradle works via the documentation on their site.

Primarily, I use Gradle to manage a version file in my game's Git repository, which is compiled into the game so that I have version information in Blueprint and C++ logic. I use that version to prevent out-of-date clients from connecting to newer servers, and having the version compiled in makes it a little more difficult for malicious clients to spoof that build number, as opposed to having it stored in one of the INI files. I also use Gradle to automate uploading my client build to Steam via the use of steamcmd.

Unreal's command line build tool is known as the Unreal Automation Tool. Any time you package from the editor, or use the Unreal Frontend Tool, you're using UAT on the back end. Epic provides handy scripts in the Engine/Build/BatchFiles directory to make use of UAT from the command line, namely RunUAT.bat. Since it's just a batch file, I can call it from a Gradle build script very easily.

Here's the Gradle task snippet I use to package and archive my client:

task packageClientUAT(type: Exec) {  
  workingDir = "[UnrealEngineDir]\\Engine\\Build\\BatchFiles"
  def projectDirSafe = project.projectDir.toString().replaceAll(/[\\]/) { m -> "\\\\" }
  def archiveDir = projectDirSafe + "\\\\Archive\\\\Client"
  def archiveDirFile = new File(archiveDir)

  if(!archiveDirFile.exists() && !archiveDirFile.mkdirs()) {
    throw new Exception("Could not create client archive directory.")

  if(!new File(archiveDir + "\\\\WindowsClient").deleteDir()) {
    throw new Exception("Could not delete final client directory.")

  commandLine "cmd", 
    "-project=\"" + projectDirSafe + "\\\\[ProjectName].uproject\"", 
    "-archivedirectory=\"" + archiveDir + "\""

My build.gradle file is in my project's directory, alongside the uproject file. This snippet will spit the packaged client out into [ProjectDir]\Archive\Client.

For the versioning, I have two files that Gradle directly modifies. The first, a simple text file, just has a number in it. In my [ProjectName]\Source[ProjectName] folder, I have a [ProjectName]Build.txt file with the current build number in it. Additionally, in that same folder, I have a C++ header file with the following in it:

#pragma once

#define [PROJECT]_BUILD_STAGE "Pre-Alpha"

Here's my Gradle task that increments the build number in that text file, and then replaces the value in the header file:

task incrementVersion {  
  doLast {
    def version = 0
    def ProjectName = "[ProjectName]"
    def vfile = new File("Source\\" + ProjectName + "\\" + ProjectName + "Build.txt")
    if(vfile.exists()) {
      String versionContents = vfile.text
      version = Integer.parseInt(versionContents)

    version += 1
    vfile.text = version

    vfile = new File("Source\\" + ProjectName + "\\" + ProjectName + "Version.h")
    if(vfile.exists()) {
      String pname = ProjectName.toUpperCase()
      String versionContents = vfile.text
      versionContents = versionContents.replaceAll(/_BUILD_NUMBER ([0-9]+)/) { m ->
        "_BUILD_NUMBER " + version
      vfile.text = versionContents

I manually edit the major and minor versions and the build stage as needed, since they don't need to update with every build. You can include that header into any C++ file that needs to know the build number, and I also have a few static methods in my game's Blueprint static library that wrap them so I can get the version numbers in Blueprint.

I also have some tasks for automatically checking those files into the Git repository and committing them:

task prepareVersion(type: Exec) {  
  workingDir = project.projectDir.toString()
  commandLine "cmd", 

task stageVersion(type: Exec, dependsOn: prepareVersion) {  
  workingDir = project.projectDir.toString()
  commandLine "cmd", 
    project.projectDir.toString() + "\\Source\\[ProjectName]\\[ProjectName]Build.txt",
    project.projectDir.toString() + "\\Source\\[ProjectName]\\[ProjectName]Version.h"

task commitVersion(type: Exec, dependsOn: stageVersion) {  
  workingDir = project.projectDir.toString()
  commandLine "cmd", 
    "\"Incrementing [ProjectName] version\""

And here's the task I use to actually push it to Steam:

task pushBuildSteam(type: Exec) {  
  doFirst {
    println "Pushing build to Steam..."

  workingDir = "[SteamworksDir]\\sdk\\tools\\ContentBuilder"
  commandLine "cmd",

You can also spit out a generated VDF file with the build number in the build's description so that it'll show up in SteamPipe. I have a single Gradle task I run that increments the build number, checks in those version files, packages both the client and server, and then uploads the packaged client to Steam. Another great thing about Gradle is that Jenkins has a solid plugin for it, so you can use Jenkins to set up a nice continuous integration pipeline for your game to push builds out regularly, which you absolutely should do if you're working with a team.

by David "Stalefish" Talley on May 7th, 2018