Jump to content
  • Advertisement
  • 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
  • Game Developer Survey


    We are looking for qualified game developers to participate in a 10-minute online survey. Qualified participants will be offered a $15 incentive for your time and insights. Click here to start!

    Take me to the survey!

  • Advertisement
  • Latest Featured Articles

  • Featured Blogs

  • Advertisement
  • Popular Now

  • Similar Content

    • By Burgos Games
      Official Website: https://nekoghostjump.com/
      Twitter: https://twitter.com/NekoGhostJump
      Developed By: Burgos Games https://burgosgames.com
      IndieDB: https://indiedb.com/games/neko-ghost-jump
      Neko Ghost Jump! is a Puzzle-Platforming Time Attack game where the player's objective is rather easy, they just need to make it to the end of the level as fast as possible. The puzzle part comes from the level design and the player's ability to shift between 2D and 3D perspectives (and as such, the need to know when/where to switch)
      It started out as a gamejam submission for Epic Games' 2019 Spring #ue4jam and we decided to continue working on it ever since then. We are currently in our 17th week of production and there have been many changes and additions and most definitely polish added.
      You can see some of the changes made in this comparison video: https://youtu.be/gthftG8rcFw

        We still have a ways to go, but progress is steady and each week brings us closer to release.  
    • By YtheTie
      Sorry I have ask a question like that on here but I can't find answers anywhere else.
      Recently I had a heated discussion with my buddy who insisted that technically all remakes are the same. 
      The example we talked about was the recently made "Link's Awakening" for Switch and the Crash Bandicoot and Spyro Trilogys.
      Could you guys shed some light on this discussion between two people with no idea how to Programm? Is the process to create a game like Link's Awakening really the same as something like Spyro? 
      Thanks for your help! 
    • By Ovva Games
      A scene from the upcoming action/adventure game Between Realms. Made with Unreal.

      What are your thoughts?
    • By doug25
      I want to start a team with the goal of creating a simple game
      this will be good project experience for working together
      The game can be 2d or 3d, might have multiple programmers
      I'm thinking a medieval/Egyptian theme fantasy possibly
      I will want one or two writers if needed, and we all may contribute to the storyline
      I think characters and dialogue can work really well-Zelda,Diablo,Neverwinter nights for example
      Looking for
      Sound ok?
      My name's dougie
      If you're interested contact me here on the forum or email me:
      sound_of_solos@hotmail.com, but beware I might not see your email because my inbox is loaded.
      I'm a C++ programmer and I use Unreal Engine as my engine of choice
      so I'll be the project lead most likely
    • By DVeNom
      Hello, my name is Sean, and I and my friends are putting together a team to create an Open-World RPG. 
      As of right, it's all volunteer work. As we are wanting in the future that it will turn into something that people will want and love. If so all the people who volunteered will see their fair share. Even if this volunteer work it's also a great chance to show your skills and learn from other volunteers who joined the project. It's a chance to increase your resume on what you learned and what you have improved.
      The concept of the game is an MMORPG. I'm taking inspiration from games like Warcraft, Elder Scrolls, and Destiny and creating something new and refreshing. First, the game was going to be about Ancient Greece Mythology and having players meet the Gods, Mythical Creatures, and mythical locations throughout the map. But I decided to go a different route to rewrite the whole story and make something original, something where the rules don't matter as the story unfolds. There will be objectives to do every week to keep you coming back. I'm going for a rich narrative to have the players really get into the world that we are creating. There will be Dungeons, Raids, PvP, World Events, and Seasonal Events to have players always wanting more. 
      What I have
      I have two concept artist and 1 3D environmental artist. I have a website designer to show our work progress once the site is up. I have two coders. I also have me as story and lore.
      Volunteering Needs
      - Lead Sound Producer
      Will need original medieval-themed music, sound effect, etc. 
      - Lead Programmer
      What I am looking for in a Programmer is someone who has the ability to program graphics, gameplay, audio, and everything else.
      2-4  3D Environmental and Character Artists.
      Needing extra hands for 3D artists to make things go smoother and faster. I'm going for a more pitcher style graphics where the world would look amazing and beautiful.
      1 Lead Writer (Lore/Character)
      Need someone to help me with the story. I love being detailed oriented and love creating ideas. I need someone who can improve on what I have done.
      If you are interested you can send me an email with your application including a sample of work at ssingl2583@my.sullivan.edu with ”RPG” as the Subject. Or you can message me on discord and my GT is D4ddy VeNom#3970. If anyone has any questions you can just message me below or the given email/discord.

Important Information

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

GameDev.net is your game development community. Create an account for your GameDev Portfolio and participate in the largest developer community in the games industry.

Sign me up!