Having a system in place to create CryENGINE project builds automatically on a regular schedule can be very useful. Having the ability to switch back and forth between older and newer builds can be vital when hunting down difficult-to-fix bugs and other problems.
Although CryENGINE builds can be created manually and then copied to a storage location, it is much easier to set up a system to automate these tasks.
Professional game development teams often have a procedure in place to create so called nightly builds. Those are builds created by a build server every night and distributed to the team the next morning. Level designers, artists, and other developers who do not directly work with C++ code or scripts are very comfortable working with nightly builds.
Those team members can just copy a fresh build every morning and can rely on the fact that everything has been properly compiled with all the latest code changes, and all .DDS files are properly created by the resource compiler. These automated builds can also serve as release candidates for your project and be used for QA testing.
In order to create automatic builds, you need to set up and configure a build server first. Your build server can be anything from a regular PC to a specifically designated workstation. Unless you are working on a really large scale project, any regular PC will do the job. You do not need to buy expensive server hardware if you are just intending to make a couple of builds per day.
In larger production environments where one build server has to handle builds for multiple large projects, stronger hardware will be needed, while for a single project with only one or two automatically generated builds per day, a normal desktop PC will do the job. Build servers for larger team sizes usually compile the code several times a day in order to catch bad check-ins as fast as possible. The more the coders work on the codebase, the more frequently should the server run the auto compilation. Professional teams of larger size will usually have dedicated personnel responsible for setting up the build servers and creating and maintaining build scripts called build engineers.
Your build server should not be the same PC you are working on, since the process of compiling a build will of course slow your machine down considerably. Using a dedicated build server rather than a local workstation also eliminates the risk of local changes ending up in an automated build.
Since the build process requires you to run the CryENGINE resource compiler as part of the asset compilation process, the build server should be running a version of Microsoft Windows. The CryENGINE resource compiler currently runs only on Microsoft Windows operating systems. Using Microsoft Windows also has the advantage that you can use the Windows scheduler to have your build scripts run automatically every night.
Once you have your build server hardware set up, it is time to create a set of build scripts, which will take care of automatically producing builds for you. Your goal will be to create a build script which takes all the latest changes done to your project by all team members and compile a new and clean build from them. Your build script should perform the following tasks:
Gathering all the latest C++ code and Lua scripts
Generating .
DDSfiles for all existing.TIFfilesDistributing the completed build to a central network location
Depending on your project, there could be several optional tasks you might want your build scripts to perform, such as the following:
Performing automated performance tests
Creating automated level benchmarks
Exporting all your game's levels
Uploading an archived version of the build to an FTP location
Creating change logs containing all changes done
A typical build process looks like this:
Overview of the build process
Now it is time to get your hands dirty and create your own build script. But don't worry, you won't have to write it all on your own, since you will be provided with a sample build script, which you can use as a base and modify to suit your needs. There is a variety of scripting languages available you could use to create your build scripts. In the following example, we are using simple batch files. Of course, you are free to use a more sophisticated scripting language, such as Python.
For this example build script, we are using Perforce and some additional software, specifically:
Beyond Compare 3
WinRAR
Visual Studio 2010
Python 3.0 or higher
Tip
There is no need to go out and buy all this software if you just want to test the build scripts. You can just use the trial versions of the software and then decide later whether you would like to keep on using them.
Before starting with the actual scripts, the computer that will function as the build server needs to be set up properly. The following steps need to be done:
Install the following software:
Beyond Compare 3
WinRAR
Perforce
Visual Studio 2010
Python 3.0 or higher
Set up a Perforce user for use in the build script, called a buildbot.
Create a folder for the build scripts.
Create a folder for the builds to be stored.
Download and extract the build script bundle from <webadress>.
Modify the settings inside
CreateFullBuild.batwith your data.
The example build scripts provided in this book require the use of a so-called Diff software. In the examples provided here, we use the software Beyond Compare 3. The software can be downloaded from http://www.scootersoftware.com/download.php.
Of course, different types of software can be used and you will just need to adjust the appropriate portions of the build script. In order to follow the examples provided in this book, the free trial version of Beyond Compare 3 will be sufficient.
This section assumes that you have a physical build server and a VCS set up already. We will be using Perforce in our example build scripts, but you can easily adjust the scripts to use SVN, Git, or any other VCS instead.
Let's have a look at the tasks that the build bot needs to perform:
Getting the latest code and assets from Perforce
Coping relevant data to a work folder
Compiling the code in 32- and 64-bit
Compiling the assets
Creating the
PAKfilesPacking up the code
Moving build to the target folder
The actual build script is rather long, so let's break it down into smaller sections and look at each section individually. To make it easier for you, the places in the script that you need to change and replace with your own folder names and project dependent settings will be pointed out in detail.
In your production environment, you can use the files from this script bundle or write your own.
To write your own script, start by creating a new text file inside your build scripts folder and call it CreateBuild.bat. Then edit it with a text editing program, such as Notepad++ and copy or type the script lines from this book. To make things easier, a text editor with syntax highlighting should be used.
The purpose of this first part of the script is just to print out some status information as follows:
@echo off cls echo. echo Creating a new full projectbuild echo------------------------------------ echoNew build started at: %date% %time%
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
These first six lines are simply clearing the console and printing the current time and date onto the screen (or into a logfile). Nothing is actually happening yet. You can safely delete and modify these lines as you like.
Printing out console output is always helpful as it gives some feedback as to where in the script the process currently is. A full build on a regular PC can take over an hour, depending on the amount of assets that need to be compiled. Knowing the current stage of the build process can be helpful to you.
These outputs will give you an insight on where your build failed if it was unsuccessful.
The next lines of the script focus on a general folder setup as follows:
G: setBuildBotPath=G:\p4\Build_Server\BuildScripts setBuildWorkPath=G:\BuildArchive\Build_InProgress setBuildSourcePath=G:\p4\Build_Server\ProjectName set BuildTargetPath=G:\BuildArchive\ProjectName_%date:~10,4%_%date:~4,2%_%date:~7,2% setVisualStudioPath=C:\Program Files\Microsoft Visual Studio 2010\Common7\IDE setBeyondComparePath= C:\Program Files\Beyond Compare 3\BComp.com setWinRarPath=C:\Program Files\WinRAR\Winrar.exe
The first command in this block of code sets the drive that the build scripts and work in progress folder for the build will be located in; in our case, this is the G drive. You will need to adjust this to the drive that your temporary build folder is located in (as set in BuildWorkPath).
The next four lines set the folder paths that are relevant for the build server. You will need to adjust each of these to point to your own folders.
BuildBotPath should point to the folder that contains the build scripts, the preceding script included. The script will need to call helper scripts and expects these to be located in this folder. Specifying a script path at the beginning of the script makes it easy to create custom versions of the build scripts for different projects on the same server.
BuildSourcePath is the path to where the local repository of the project is located on the hard disk of the build server. In case the build server is also used as a work machine, this should not be the path to the local work directory. The build bot should have its own login and local work directory for the versioning system.
BuildWorkPath is a temporary folder that is only used for copying and compiling the build. After it is done, it will be moved to a final target folder. This folder is usually shared on a network drive. The move to the final folder doesn't happen until the entire build script is done, to avoid users copying down unfinished builds.
BuildTargetPath is the final target folder for the build. This will be autogenerated from the project name and the current date. If you are planning on having more than one build per day, you could consider adding a time stamp to the folder. This autogenerated folder name will make sorting the builds by date very simple.
Lastly, you will need to provide the installation locations for Beyond Compare 3, WinRar, and Visual Studio, in the variables VisualStudioPath, VisualStudioPath, and WinRarPath respectively.
Now, it's time to update the code and assets from Perforce as follows:
echo. echo Retrieving the latest from the version control p4 -c WORKSPACE -p PERFORCE_SERVER:1666 -P PASSWORD -u USERNAME login p4 sync -q //PROJECTNAME/...#head echo Done.
In this part of the script, you will need to replace everything that is printed in CAPITAL letters with your own version control data. The //PROJECTNAME/ term in the fourth line is the depot path of your repository that you want to retrieve. If you have chosen SVN or Git as your version control software, you will need to replace the appropriate calls.
If you are using your PC as a work station and build server simultaneously, and have more than one workspace mapped to the same machine, you might need to change the lines to the following, since the environment variables will probably not be set to the build server's user and workspace. This also applies if you don't have a password set up for your build bot user, as follows:
p4 -c WORKSPACE -u USERNAME sync -q //PROJECTNAME/...#head
Now it is time to copy all the relevant data into the temporary work folder and compile it. This folder might or might not exist yet. If it does, it needs to be cleared first so that no old data mixes with the new clean build as follows:
if exist "%BuildWorkPath%" ( echo. echoClearing out temporary Work Folder echo %BuildWorkPath% rmdir /S /Q "%BuildWorkPath%" )
Next, the data can be copied from the local repository folder to the work folder as follows:
echo. echo Copy build relevant data echo to %BuildWorkPath% mkdir "%BuildWorkPath%" cd %BuildBotPath% %BeyondComparePath%/closescript "@CopyBuildScript.txt" echoDone.
This bit of the script calls upon Beyond Compare, a folder diff tool, to copy the build into the work folder. This is done because not all of the files from the repository are required for the build. Source assets, for example, Photoshop, 3ds Max, or ZBrush files need to be removed. These files are commonly rather large and would unnecessarily bloat up the build size. Also, the build server's task is to create release candidates, and source assets are usually not shipped.
Beyond Compare 3 can filter out all files that are not desired in the final released build. The script bundle available for download with this book includes a script that filters out the most common source asset types. The script is called CopyBuildScript.txt and is called upon in the preceding script block.
If Beyond Compare 3 is installed in a different location on your computer, you will need to adjust the path to BComp.com in the script. If you are using a different folder diff tool, you can replace this part completely with the appropriate calls to your tool.
Another function the script performs is to remove the read-only flag on all copied files. Many version control systems such as Perforce set a read-only flag on all files in the local repository unless they are checked out, and the script takes care of this. The files need to be writable so that build script can compile, pack, and delete files later.
Now the code can finally be compiled as follows:
echo. mkdir "%BuildWorkPath%\Logfiles" cd %BuildWorkPath%\Code\Solutions echo Compiling 64 Bit "%VisualStudioPath%\devenv.com" CryEngine.sln /rebuild "Profile|x64" > "%BuildWorkPath%\Logfiles\Log_64Bit.txt" echo Compiling 32 Bit "%VisualStudioPath%\devenv.com" CryEngine.sln /rebuild "Profile|Win32" > "%BuildWorkPath%\Logfiles\Log_32Bit.txt" echo Done.
The first half of this script block creates a subfolder within the build folder to store the logfiles in. This is optional but can be very useful if there are any compilation errors for either code or assets. It is a good first place to start looking in when a build fails.
Next, the command-line version of the Visual Studio compiler is called upon to compile the first 64-bit and then 32-bit of the project.
Then, the path to the Visual Studio installation is set to the default installation location. If your Visual Studio is installed in a different directory, you will need to adjust this path.
You will also need to replace the CryEngine.sln filename with your own solution filename should you change it.
Logfiles will be saved to the Logfiles subfolder. The FreeSDK release solution file is usually named differently than the full source release.
Tip
At the time of writing this book, the default solution file for the CryENGINE release requires the Visual Studio 2010 compilers. Future releases of CryENGINE might require Visual Studio 2012 or up. You will need to adjust the folder path in this case.
Compiling the code will create temporary files, such as for example *.pdb files containing debug information. These files need to be removed as they should not be part of a release candidate. They would increase the build size and could potentially be used to reverse engineer your code.
The following part of our build script will remove these files and folders:
echo. echo Removing temporary files from Code Build cd %BuildWorkPath%\Bin32 del *.lib del *.pdb del *.exp delCryAction.map cd %BuildWorkPath%\Bin64 del *.lib del *.pdb del *.exp delCryAction.map cd %BuildWorkPath% rmdir /S /Q BinTemp
These instructions are for a full source build of CryENGINE. If only the game code is compiled, the lines concerning Cry Action can be removed.
The code is compiled now, so it is time to take care of the assets as follows:
echo. echo Compile Assets cd %BuildWorkPath% echo Compiling Objects... .\Bin32\RC\rc.exe .\Game\Objects\* /p=PC /ext_dds /ext_cba /recursive /threads=cores /processes=cores > ".\Logfiles\AssetCompilationLog_Objects.txt" echo Compiling Libs... .\Bin32\RC\rc.exe .\Game\Libs\* /p=PC /ext_dds /ext_cba/recursive /threads=cores /processes=cores > ".\Logfiles\AssetCompilationLog_Libs.txt" echo Compiling Textures... .\Bin32\RC\rc.exe .\Game\Textures\* /p=PC /ext_dds /ext_cba /recursive /threads=cores /processes=cores > ".\Logfiles\AssetCompilationLog_Textures.txt" echo Compiling Materials... .\Bin32\RC\rc.exe .\Game\Materials\* /p=PC /ext_dds /ext_cba /recursive /threads=cores /processes=cores > ".\Logfiles\AssetCompilationLog_Materials.txt" echo Compiling Levels... .\Bin32\RC\rc.exe .\Game\Levels\* /p=PC /ext_dds /ext_cba /recursive /threads=cores /processes=cores > ".\Logfiles\AssetCompilationLog_Levels.txt" Echo Done.
The preceding line makes several calls to the resource compiler located by default in the RC folder under Bin32, shipped with any version of CryENGINE, to compile the assets. The resource compiler's output will be piped into a separate text file inside the Logfiles folder. Asset compilation will run over all data files (geometry, images, and so on) and process it. For images, this means compiling and converting them into platform specific and optimized .DDS files.
The XML file that contains the job description is provided with the CryENGINE build. However, if you have changed your default game folder from GameSDK to a folder of a different name, you will need to open the RCJob_Build_SDK_no_scripts.xml file in a text editor and adjust the folder name in the default properties at the top of the file.
This step in the build process usually takes the longest. Using a build server with multiple CPU cores can significantly speed up the process. While giving a definitive speed advantage, multiple threads will create a less detailed log output. To get a log entry for every asset that was processed and error codes, remove the parameters /threads=cores /processes=cores from the call in the preceding script.
Tip
To get a list of all the console parameters for the resource compiler in a text file, type ./Bin32/RC/rc.exe /help > RCCommands.txt in the console in the build's root folder. It will create a file RCCommands.txt in the root, containing documentation for each parameter.
For projects that create automated builds several times a day, it is sensible to create a separate build script that will only compile the code and copy the already compiled assets from the last build into it, for a faster turnaround time.
After all assets are processed by the resource compiler, the now duplicate .TIF file can be removed as follows:
echo. echo Remove redundant tif files cd %BuildWorkPath%\Game copy "%BuildBotPath%\delete_redundant_tifs.py" .\. delete_redundant_tifs.py del delete_redundant_tifs.py
After the processing of the assets, the resource compiler will have created a DDS file for all .TIF files it could find in the directories. The .TIF files are considered source files and should not be shipped to end users. They are also usually rather large and would unnecessarily bloat up the build. The Python script delete_redundant_tifs.py traverses through the game folder and its subfolders and removes all those .TIF files that have a corresponding .DDS file. This script is included in the script bundle available for download and requires Python to run.
After this clean-up step, the assets need to be compressed into PAK files:
echo. echo creating PAK files and deleting original folders cd %BuildWorkPath%\Game echo. echo Creating Objects.pak "%WinRarPath%" a -r Objects.zip .\Objects rename Objects.zip Objects.pak rmdir /S /Q Objects echo Creating Animations.pak "%WinRarPath%" a -r Animations.zip .\Animations rename Animations.zip Animations.pak rmdir /S /Q Animations echo Creating GameData.pak "%WinRarPath%" a -r GameData.zip .\Entities .\Libs .\Scripts .\Prefabs .\Fonts rename GameData.zip GameData.pak rmdir /S /Q Entities rmdir /S /Q Libs rmdir /S /Q Scripts rmdir /S /Q Prefabs rmdir /S /Q Fonts echo Creating Sounds.pak "%WinRarPath%" a -r Sounds.zip .\Music .\Sounds .\Languages .\Localized rename Sounds.zip Sounds.pak rmdir /S /Q Music rmdir /S /Q Sounds rmdir /S /Q Languages rmdir /S /Q Localized echo Creating Textures.pak "%WinRarPath%" a -r Textures.zip .\Materials .\Textures rename Textures.zip Textures.pak rmdir /S /Q Materials rmdir /S /Q Textures
PAK files are simple ZIP files with a different ending. Common compression software, such as WinRAR and 7-Zip can open and create these files. In this example, we will use WinRAR to create the PAK files.
After each PAK file is created, the source folders are deleted with the rmdir commands. This setup will create five different PAK files, combining the various folders into easily shippable containers.
Tip
It is possible to let the resource compiler compile the assets and create the PAK files automatically by using a job XML configuration file. Most CryENGINE releases ship with one or more example job XML files inside the RC folder under Bin32.
These example files usually need to be heavily modified before it will work for custom builds. The names and contents of these files change with each release so they are not used in this build script example to prevent version conflicts.
After this has finished, the source code can be either packed or removed as follows:
echo. echo -- Zip the Code folder (and delete) -- cd %BuildWorkPath% "%WinRarPath%" a -r Code.zip .\Code rmdir /S /Q Code
The zipped code should of course not be shipped to end users. However, it can be useful to keep the code that was used for compilation as part of the build inside the internal build archive. It sometimes becomes necessary during production to use an older build, for example, for demonstrations or for bug hunting. In these cases, it can be extremely useful to be able to access the code used for the creation of the build quickly and without version control hassle.
After this last step, the build is finished. It can now be moved to the target location, usually on a shared network drive, as follows:
echo. echo -- Rename Build folder -- cd %BuildWorkPath% cd.. move "%BuildWorkPath%" "%BuildTargetPath%" echo. echo Build Finished: %date% %time% echo ==================== echo Build Done. echo.
The build script developed in this chapter is by no means the single and only way to create CryENGINE builds. This should serve as base line to get you started. During the development of your project, you will most likely want to extend and customize the build scripts to better suit your needs.
The preceding build script will output some status messages onto the console it was started from. For builds started manually, this works fine. If the console output is collected as well, a simple wrapper script can call the build script and pipe its entire output into a logfile.
The following code snippet is an example of such a wrapper script. It is included in the scripts bundle and the file is called BuildWithLogFile.bat:
This script will create a logfile called
BuildLog.txt and move it into the Logfiles folder of the newly created build after it is finished. The usage of such a wrapper script is recommended for automated builds.
@echo off cls echo Starting new Build echo ====================================== echoLogfile will be saved to BuildLog.txt echo Build Started: %date% %time% callCreateBuild.bat > "BuildLog.txt" move "%BuildBotPath%\BuildLog.txt" "%BuildTargetPath%\Logfiles\BuildLog.txt" echo ====================================== echo Build done.
To create builds at a fixed time during the day, we need to start the build script automatically at specified times. This can be done with the Windows Task Scheduler. This feature allows you to run certain programs or scripts repeatedly at predefined dates and times.
The task scheduler can be accessed via the Windows Control Panel. Go to System and Security and then find the task scheduler under the section called Administrative Tools.
Create a new task by selecting Create Basic Task from the Actions bar on the right. Enter a name and a brief description for the new task, for example, Daily Overnight Build.
Next, you will need to specify a frequency at which to run the build script. For fulltime development projects with a dedicated build server, we recommend creating a build at least daily. For hobby projects, or projects with a smaller team size, creating weekly builds might be enough. Creating too frequent builds with very little changes in between them will only be a waste of hard disk space, so choose according to your project needs.
Tip
Choosing the weekly frequency will give you the most customization options. After selecting this setting, you can choose the individual days of the week on which the task should run. For hobby and mod teams working mainly on the weekend, daily builds on Friday through Monday might not make so much sense. Development teams working fulltime will probably want to choose a setting of one build daily during the work week, but none on the weekends.
The task creation wizard seen in the following screenshot makes it easy to schedule automatic builds:
In many development studios, the build server will also host the version control system, internal documentation, and bug tracking services and potentially serve as a network drive.
To prevent the automated builds from causing a performance hit on the server during work hours, it is sensible to schedule the task at a time when it is most likely that no one needs the server for other purposes, such as during the night or the early morning hours.
After the frequency has been set, we can define what action should be performed when the task is executed. Choose Start a Program from the list and click on Next.
The next page of the wizard will ask you to provide the program or script that should be run. Use the Browse button to select the BuildWithLogFile.bat script. Also, set the path that contains the build scripts in the edit field labeled Start in.
Hit Next and Finish to finalize the process. If you want to test your task, you can either set the frequency to a one-time run a few minutes from the current time, or manually select the task from the Task Scheduler Library and then Run from the right-click menu.
A console window should open showing the log output from the build script.
The automated task will create clean builds of your project at the set frequency for as long as you keep the task active in the task scheduler. The builds will be collected in the build archive folder you specified in the script. From time to time, you might want to go through that folder and delete older builds or archive them to another storage location.
Tip
Don't delete all of your old builds as they can be extremely handy at the end of your development when tracking down resilient and hard-to-find bugs. Keep at least one build from every month's development to help you narrow down timeframes when a certain bug first appears. This makes the process of finding the culprit changelist a lot faster.