Build and bundle assets for release in Lumberyard
Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE |
This tutorial guides you through the process of building the code and assets to release a Lumberyard project, using the Starter Game sample project. You'll learn how to:
Create a release build of your game's executable.
Set up the directory structure of a release build.
Compile shaders and generate shader paks.
Compile auxiliary data, like configuration information and gem assets.
Create bundled content using the asset bundling system.
Run a stand-alone release build for your project.
Prerequisites
To complete the procedures in this tutorial, you need the following:
-
Amazon Lumberyard. Download the latest version of Amazon Lumberyard
. -
Visual Studio 2017 or Visual Studio 2019 installed and configured to develop with C++. This tutorial uses commands for building with Visual Studio 2019. If you use Visual Studio 2017, change any reference to
tovc142
and any references tovc141
tovs2019
. Download Visual Studio from Microsoftvs2017
. -
(Recommended) Some familiarity with the Asset Bundler concepts and terminology. This tutorial uses seed lists and asset lists to generate bundles.
Configure Lumberyard to build the Starter Game project
-
Open the Amazon Lumberyard Project Configurator.
-
Select Starter Game and then select Set as default in the upper-right corner of the Project Configurator screen.
-
Open a command prompt and navigate to the Lumberyard root directory at
.lumberyard_dir
\dev -
Configure the build system for Starter Game and generate configuration files:
lmbr_waf configure
Create a release build
-
Open a command prompt and navigate to the Lumberyard install root directory.
-
Create a profile build using the all build spec. Depending on your hardware, this can take a while.
lmbr_waf build_win_x64_
vs2019
_profile -p allThis step ensures that your editor, asset processor, asset builders, and other edit-time content is up to date. It's also required for shader generation.
-
Make a release build with the game_and_engine build spec. Depending on your hardware, this can take a while, but should be faster than a full profile build.
lmbr_waf build_win_x64_
vs2019
_release -p game_and_engine
Create a directory structure for the game release
-
Open a command prompt and navigate to the Lumberyard install root directory.
-
Create a directory for your game release. The following command creates the release directory
C:\Users\
:username
\StarterGameReleasemkdir %USERPROFILE%\StarterGameRelease
Note You can create this directory anywhere you want, but the rest of this tutorial assumes the release directory is in this location. It's not recommended that you create this directory anywhere inside of your Lumberyard install. If you do, detecting missing assets and diagnosing bundle problems becomes more difficult.
-
Create a subdirectory that will contain the game binaries and libraries:
mkdir %USERPROFILE%\StarterGameRelease\release
-
Copy the contents of the release build into the
StarterGameRelease\release
directory:xcopy /s Bin64
vc142
.Release %USERPROFILE%\StarterGameRelease\releaseIf prompted Does
path
specify a file name or directory name on the target?, chooseDirectory
.Note Release builds include some metadata like debug symbols in a
.pdb
file. When releasing your game, make sure to delete any compiler metadata that's copied over that isn't needed for launching or running your game. -
Create a subdirectory that will contain the game data:
mkdir %USERPROFILE%\StarterGameRelease\startergame
The remaining steps in this tutorial show how to build and copy your game data to this directory.
Export level data
-
Open the Lumberyard Editor and load the Starter Game level by selecting File > Open Level (Ctrl+O) and selecting the SinglePlayer level.
-
Select Game > Play Game (Ctrl+G) from the Editor's main menu to enter Game mode. Roam through the level to load the shader assets. Make sure that you view as much of the level as possible, in order to load them all.
You can also load shaders by flying the camera through the editor's viewport, but make sure that you load shaders around the player's starting area. Otherwise, running the standalone game executable will show a black screen.
-
Select Game > Export to Engine (Ctrl+E) from the Editor's main menu to export the level data to a
.pak
.
Generate shaders and auxiliary data
-
Open a command prompt and navigate to
.lumberyard_dir
\dev\Tools\CrySCompileServer\x64\profile -
Start the shader compiler. Don't close the command prompt.
CrySCompileServer.exe
-
Open a second command prompt and navigate to the Lumberyard install root directory.
-
Compile and package the shaders:
lmbr_pak_shaders.bat StarterGame D3D11 pc
After building the shaders, close the command prompt window where
CrySCompileServer.exe
is running. -
Copy the shader
.pak
files generated by the compiler into the game data folder:copy build\pc\StarterGame\* %USERPROFILE%\StarterGameRelease\startergame
-
Generate the game's auxiliary data:
Tools\Python\python3 BuildReleaseAuxiliaryContent.py --platforms pc --buildFolder Bin64
vc142
The auxiliary data includes configuration information for the engine and game loading and level data.
-
Copy the auxiliary data to the release directory:
xcopy /s startergame_pc_paks %USERPROFILE%\StarterGameRelease
Generate game asset bundles
-
Open a command prompt and navigate to the Lumberyard install root directory.
-
Bundle assets needed by the game engine:
Bin64
vc142
\AssetBundlerBatch.exe assetLists --addDefaultSeedListFiles --assetListFile engine.assetlist Bin64vc142
\AssetBundlerBatch.exe bundles --assetListFile engine_pc.assetlist --outputBundlePath %USERPROFILE%\StarterGameRelease\startergame\engine.pakThis generates the
engine_pc.pak
file in your release folder. The engine pak contains the assets required by the engine and gems. -
Bundle game content and level assets:
Bin64
vc142
\AssetBundlerBatch.exe assetLists ^ --addSeed Levels\Game\SinglePlayer\level.pak ^ --addSeed project.json ^ --addSeed gems.json ^ --addSeed scripts/ai/navigation.xml ^ --assetListFile startergame.assetlist Bin64vc142
\AssetBundlerBatch.exe bundles --assetListFile startergame_pc.assetlist --outputBundlePath %USERPROFILE%\StarterGameRelease\startergame\startergame.pakThis generates the
startergame_pc.pak
file in your release folder.Important --addSeed
takes a path relative to your project folder (for source assets) or the asset cache (for product assets). For Starter Game, project source assets are located in
. Don't use absolute paths or paths relative to the current directory when adding a seed.lumberyard_dir
\dev\StarterGame
Run your packaged release
Open a command prompt and navigate to your packaged release at
%USERPROFILE%\StarterGameRelease
.Run the launcher executable for your game and load the map:
release\StarterGameLauncher.exe +map singleplayer
If your content bundles are correct, the starter game will load and be playable. Use Alt+F4 to exit the game.
If objects are displayed but textures are missing, it probably means you forgot to export
the level before packaging assets or didn't add the level.pak
file as a
seed. You could also be missing some shaders - run through the level and build the shader package
again.
If the test isn't successful, common issues may occur. For example, error messages may display, the launcher may shut down, or a black screen displays. For more information about troubleshooting common issues, see Resolving Missing Assets and Compiling Shaders for Release Builds.
When you run the release build, it creates a User
subdirectory under
your release build directory. Be sure to delete this directory before shipping the release
build.
Next Steps
Now that you've learned the basics of bundling assets for release, go on to further reading:
Learn about how bundles are mounted, so that you can load content dynamically. See Creating Multiple Asset Bundles.
Explore the asset bundler functionality. See Lumberyard Asset Bundler Command-Line Tool Reference.
Learn how to scan for missing dependencies in your bundles. See Using the Missing Dependency Scanner
To ask questions about the Asset Bundler and get support, see the Amazon Lumberyard forums
.