This guide takes a detailed look at the end to end build process involved in creating a packaged game build with Amazon Lumberyard. A packaged build is a standalone version of your game which can be distributed to friends, publishers or players.
At the time of writing, the packaging process is entirely command line driven and requires a few manual steps. It is certainly a little time-consuming to set-up at first, but thereafter it can be scripted using the steps below. With this approach we can cut new builds at any time with minimal effort; something which we typically do once a day or a little more frequently if we’re preparing a release for an upcoming demo.
The complete build pipeline is made up of 10 distinct steps which we’ll examine one at a time.
Step 1. Run set-up assistant
The Lumberyard set-up assistant ensures that required third party SDKs and system tools are installed and configured correctly. Normally you run the GUI version of this tool when you first install Lumberyard and you don’t need to run it again. When making an automated build we run it each time as we may be initialising a new build machine or code branch. Either way, it’s an important step as it ensures that the various SDKs are configured and it is responsible for setting up the symbolic links between the dev\Code\SDKs and 3rdParty folders.
The SetupAssistant can be run from the command line, pass in arguments to enable the various capabilities that your game needs. To see a complete list of capabilities run SetupAssistantBatch.exe with the –help argument.
Here’s an example command that we use, the –none option disables all capabilities and then we re-enable the ones that we need. We’re using Visual Studio 2015 for this guide, so if you’re running 2013 you’ll need to enable the vc120 capability instead and also modify several of the build commands further down in this guide.
SetupAssistantBatch.exe --none --enablecapability compilegame --enablecapability compileengine --enablecapability compilesandbox --enablecapability vc140
Step 2. Configure the build
Once we have a working installation we first need to configure the Lumberyard build system before we can compile any code, this step checks our system setup and gathers the various dependencies between code files.
In a command line window navigate to the dev folder under your Lumberyard installation and run the lmbr_waf configure command:
cd dev lmbr_waf configure
Step 3. Build the editor and asset tools
It’s good practice to ensure that the editor and related tools are up-to-date before making a build. This includes the asset processor and the resource compiler which are used to build the data. You can skip this step if you’ve not modified the Lumberyard engine code, otherwise go ahead and build the editor with the following command:
lmbr_waf build_win_x64_vs2015_profile -p all
Step 4. Build the game code
Next, you’ll build the executables for your game. At this point you’ll need to consider what type of build you want to create:
Profile or Release binaries?
Release builds are used for the final game, they don’t include any debug commands or the console and have limited logging.
Profile builds are used during development, they have good performance and include several essential debugging and profiling tools.
For more information about the differences see the Game Builds section of the Lumberyard docs.
If this is you first time making a build then I recommend using Profile as the diagnostics are much better if things don’t work. Release builds are also susceptible to issues that you won’t have seen in dev and may require a little more work to get going.
If you choose Profile then the game exe will have already been output to the Bin64vc140 folder when you built the editor in the previous step. Otherwise, for a release build (which is a separate configuration) you will need to build the executable with the following command:
lmbr_waf build_win_x64_vs2015_release -p game_and_engine
Does your game use a dedicated server?
If so, you’ll want to build the server configuration as well, build it for either release or profile as follows.
lmbr_waf build_win_x64_vs2015_profile_dedicated -p dedicated_server
lmbr_waf build_win_x64_vs2015_release_dedicated -p dedicated_server
Step 5. Export the levels
Before a level is playable in a standalone or launcher build it must be exported from the editor, this can be done by opening the level in the editor and selecting “export to engine” from the Game menu.
This action creates a packaged level asset which will be collated into the build in a later step. You can double check that it was created by looking for it at:
Automating the export
If you have many levels or a lot of people working simultaneously then automating this step is worthwhile. Amazon provides a rudimentary script to perform the legwork here. The provided script automates editor actions, it loads up the editor, opens each level in turn and exports it.
You can run it as follows:
bin64vc140\Editor.exe /BatchMode /runpython "drive letter and Lumberyard path\dev\Editor\Scripts\export_all_levels.py"
A word of caution, the script is less than ideal for an automated pipeline. Calling an editor script from a command line returns immediately with no output and the editor then fires up and runs sluggishly in the background often skipping over errors or becoming unresponsive.
For this reason, our designer and artist typically export by hand when they update a level and submit the resulting pak file to Perforce. This makes it available to other users and the build machines immediately without the need for an automated export.
That said this manual approach has caught us out on a few occasions when the pak has been exported from out of date files. It would be great to see an offline version of this script or better yet have the level export integrated into to the asset processor. This would bring it in line with the rest of the asset pipelines used in the engine.
Step 6. Process the assets
The next step is to run the Lumberyard asset processor to convert the raw game assets into optimised platform-specific versions. Normally the asset processor sits in your system tray and monitors your disk for new or updated assets converting them automatically when it finds them. The tool can also be used from the command line in which case it scans for all assets which were modified since the previous run and updates the game ready versions in the local cache.
In the example below, we’re building the default SamplesProject but you’ll need to replace this with the name of your project. Check in the Project Configurator if you’re unsure of the project name.
dev\bin64vc140\AssetProcessorBatch.exe /gamefolder=SamplesProject /platforms=pc
Step 7. Package assets into PAK files
Next, to bundle our assets into PAK files, this step takes the game ready assets from the cache folder and bundles them into zip files with a .pak extension. These pak files are then distributed with the build and contain all of the assets that your game requires.
Up-until now we’ve actually been building the code and assets in an identical manner to dev. This is the first step in which we build data specifically for the stand-alone version of the build. This means that we need to choose a new folder to contain our packaged assets and game exes ready for distribution. For the purpose of the guide the folder is
This will be a folder that you can zip up or copy between machines or otherwise build in to the installer for your game.
Now back to the task at hand, generating the pak files. To do this we run the Lumberyard resource compiler with a job file which is configured to create the paks in the output folder. An example command looks like this:
cd dev bin64vc140\rc\rc.exe /job=Bin64/rc/RCJob_Generic_MakePaks.xml /p=pc /game=samplesproject /trg=c:\PackagedBuild
The arguments for this command are as follows:
- The /job argument links to the “RCJob_Generic_MakePaks.xml” this file is used to configure which assets are shipped in the build and also how they are organised into pak files.
- The /p argument specifies the platform, this guide is for PC.
- The /game argument should be replaced with the name of your game.
- The /trg argument specifies the output location for the packaged build, the pak files will be written into this folder.
Once the command completes inspect the contents of the C:\PackagedBuild folder. It should contain a number of game cfg files, and a samplesproject sub-folder with all the pak files for the game.
Step 8. Compile the shaders
In development builds, the Lumberyard engine loads shader source files and compiles them on the fly. This happens the first time the shader is needed and the results are saved back to the cache. In release builds this functionality is undesirable as it causes performance drops and visual glitches as the player moves through the level. To avoid these issues we upfront compile the shaders for the target platform and package them into the build.
The shader pipeline in Lumberyard 1.9 isn’t fully automated as the generator requires a list of all the shaders which are used in your levels and their respective parameters. Currently, the only official way to generate that list is to play through all levels or load them in the editor and fly through all locations. This will generate a file in the cache which contains a list of the shaders used by the game.
To compile and pack the shaders, there’s a batch file in the dev folder named BuildShaderPak_DX11.bat. This file is hard-coded to the SamplesProject so you will need to edit it first and update the game name.
... set SOURCESHADERLIST=%1 set GAMENAME=SamplesProject set DESTSHADERFOLDER=Cache\%GAMENAME%\PC\user\Cache\Shaders ...
Then run the batch file from the dev folder.
cd dev BuildShaderPak_DX11.bat
This generates 2 PAK files under dev\Build\pc\SamplesProject\D3D11
To complete this step copy these pak files into your packaged build, such that they sit alongside the other pak files under C:\PackagedBuild\SamplesProject
Step 9. Copy the executables
Earlier you built your game executable into one of the dev\Bin64* folders and you must ship these exes with the package, this can be achieved by simply copying the whole folder such that it ends up in a location like c:\PackagedBuild\Bin64vc140.
You’ll need to copy the bin folder which corresponds to the version that you built earlier.
When copying the exes you can actually rename the folder to anything you like. For example, you might choose to just call it “bin”. You can also include multiple configurations, so if you want both Release and Profile just copy both folders.
It’s worth noting that the bin folder contains more data than is necessary for the build to be distributable. To keep the package size down we typically strip out pdb files (debugging databases), unnecessary executables (such as AssetProcessor.exe and Editor.exe) and assemblies which are only needed by the editor (such as qt5webkit.dll).
Step 10. Configure the standalone package
The final step of mastering your packaged build is to make any adjustments to the run-time environment. This is done by editing the .cfg files which are packaged as loose files with your build:
This file lives in the root of your c:\PackagedBuild folder. If you’re shipping Profile or Debug exes then you should disable the asset processor from launching when the game boots. This is done by finding the line “connect_to_remote” and setting it to 0.
This file configures the default resolution, fullscreen options and graphical fidelity for the game. Changing it is optional but you may wish to tweak certain settings for your needs. For example, to run fullscreen at 1080p using “very high” system spec you can set the variables as follows:
r_Width = 1920 r_Height = 1080 r_Fullscreen = 1 sys_spec = 4
Use this file to set any additional console variables which configure your game. These can be your own custom variables or the built-in ones. For example, to turn off the onscreen debug diagnostics in a profile build you might add:
You can use this command to run console commands on boot. For example, if you want the game to load into a particular level you can add:
Ready to Roll?
That’s it we’re ready to give our package a spin, to launch simply run the executable from the C:\PackagedBuild folder.
If all goes well your game (or sample project) should load up and be ready to play. You can now copy the package to machines which don’t have Lumberyard.