Jump to content
  • Advertisement
  • Remove ads and support GameDev.net for only $3. Learn more: The New GDNet+: No Ads!

  • 05/21/18 02:53 AM
    Sign in to follow this  

    Using Gradle to version and build a UE4 project

    Engines and Middleware


    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_NUMBER ###
    #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.

      Report Article
    Sign in to follow this  

    User Feedback

    There are no comments to display.

    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

  • Advertisement
  • Advertisement
  • Latest Featured Articles

  • Featured Blogs

  • Popular Now

  • Similar Content

    • By Novakin
      HI everyone
        We are looking for a game designer to assist with creating a game. It is a 3D first/third person battle simulator. Its set in the Viking age in Norway and we want to create a brutal but fun game with focus game mechanics. We would like to have a stamina system that is linked to a weapon and armour weight system. This system will require management from the player if they hope to survive. I have a rough GDD but I need a game designer to re write it and make it better. This project is intended to be commerical so if all goes well, you will recieve a share. You will also be doing other game design jobs throught the project. We have a handful of other devs that will be working on this, 3d artists, a programmer and concept. If you are reading this and your not a game designer but want to be involved please message me as we are still looking for other devs and artists but we cant start until the gdd is complete.
      thank you
    • By Rob_I
      I have a specific need to launch a game from an existing app.  Has anyone come across a game engine that can be built in this way?  Any help would be appreciated.
      Thank you!
    • By Brizzler
      Hey Everyone, 
      I'd like to review some of your indies games! I'm interested in games made for the Universal Windows Platform (UWP).
      Reply to this post if your interested in having your games reviewed and youtubed on my channel:
    • By 999PING
      I'm very often facing one small problem when trying to learn some new stuff - hard to choose what to learn next.
      Even if the problem seems to be small it has a very huge impact on the final result I think. And because Game Programming offers so much to learn, I'm always feeling that I'm missing something important and wasting my time learning something not important or unneeded. Or usually, I'm afraid to focus on something specific and huge for a long time, because I think that I'll spend all my time on that particular filed and will not be able to solve another problem.
      So I've tried to fit all my thoughts in this questions.
      1) Are you trying to cover all the aspects of Game Programming? Or you trying to focus on some specific aspects like physics, animations, or networking etc.
      2) What is your way to find a new theory or whatever else for your learning process? (Manuals, Courses, Books, Documentation? etc.)
      3) When you trying to learn while practicing, are you search for learning because of a problem that appears, or because you wants to try new things? How do you choose this new thing? And finally, Which of this two approaches was the best for you if any?
      Not actually in the scope of the topic, but I'm also very interested to hear your thoughts on this.
      What is Game Programming for you? How would you describe what should Game Programmer able to solve?
    • By ZOSK
      Here are some tips and tricks that will help you in Unreal Engine. Feel free to add some in the comment section ! 
      Duplicating assets in the viewport : An easy way to duplicate assets directly in the viewport is to hold down the alt key, and then use a transformation tool to duplicate it.
      Switching transformation tools : The best way to switch between translate, rotate, and size is to press the corresponding key : W to translate, E to rotate, and R to resize. You can cycle between them by pressing the space key. You can also manually select one by clicking on one of the three corresponding icons in the upper right corner of the viewport. 
      Hide editor UI : The viewport’s UI can often be annoying when creating and editing the level, but you can easily hide it. Press the G key to hide/show the UI.
      Fullscreen : If you want to play your game fullscreen without having to play it as standalone or new window, you can just run it in the viewport and press F11, to toggle fullscreen. This feature is also available while the game isn’t playing, so you can edit the level in fullscreen. 
      Show/Hide nav mesh bounds volume area : If you are using a nav mesh bounds volume in your level, you can show it’s area by pressing P. Surfaces inside the nav mesh bounds volume will have a green surface.
      Hiding viewport alerts : While you create your game, you will end up with warnings like “Lightning needs to be rebuilt” ans other alerts. These can be annoying while running the game, because they show up over your game. To hide them, you can use the Execute console command node in any blueprint, with “DisableAllScreenMessages” as command.
      Quickly create nodes : There are a few nodes that you can create by holding the corresponding key and then left-clicking. Here are the keys : Branch (B+Left-click), Delay (D+Left-click), Sequence (S+Left-click), Gate (G+Left-click), ForEachLoop (F+Left-click) Multi-gate (M+Left-click), Do N times (N+Left-click), Do once (O+Left-click), Event beginPlay (P+Left-click). 
      Renaming : You can easily rename assets, nodes, comments and many other things by clicking the item and then pressing F2.
      Duplicating nodes : Easily duplicate nodes by selecting one, and then pressing CTRL+W.
      Selecting multiple nodes : Hold shift and left-click nodes or select them with the box selection to select multiple nodes.
      Quickly run the game : Press alt+p to play the game from anywhere in the editor. The game will play in the viewport if the current window is the level window, and in a new window otherwise.
      Adding windows : If you remove a window like the content browser by accident, you can get it back by opening the window drop-down list on the top of the editor. After that, select the window you want to add. 
  • Advertisement

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!