Build and bundle assets for release in Lumberyard - Lumberyard User Guide
PrerequisitesConfigure Lumberyard to build the Starter Game projectCreate a release buildCreate a directory structure for the game releaseExport level dataGenerate shaders and auxiliary dataGenerate game asset bundlesRun your packaged releaseNext Steps

Build and bundle assets for release in Lumberyard

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

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:

Configure Lumberyard to build the Starter Game project

  1. Open the Amazon Lumberyard Project Configurator.

  2. Select Starter Game and then select Set as default in the upper-right corner of the Project Configurator screen.

    Setting the Starter Game as the default project from the Project Configurator.

  3. Open a command prompt and navigate to the Lumberyard root directory at lumberyard_dir\dev.

  4. Configure the build system for Starter Game and generate configuration files:

    lmbr_waf configure

Create a release build

  1. Open a command prompt and navigate to the Lumberyard install root directory.

  2. 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 all

    This 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.

  3. 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

  1. Open a command prompt and navigate to the Lumberyard install root directory.

  2. Create a directory for your game release. The following command creates the release directory C:\Users\username\StarterGameRelease:

    mkdir %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.

  3. Create a subdirectory that will contain the game binaries and libraries:

    mkdir %USERPROFILE%\StarterGameRelease\release

  4. Copy the contents of the release build into the StarterGameRelease\release directory:

    xcopy /s Bin64vc142.Release %USERPROFILE%\StarterGameRelease\release

    If prompted Does path specify a file name or directory name on the target?, choose Directory.

    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.

  5. 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

  1. Open the Lumberyard Editor and load the Starter Game level by selecting File > Open Level (Ctrl+O) and selecting the SinglePlayer level.

  2. 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.

  3. 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

  1. Open a command prompt and navigate to lumberyard_dir\dev\Tools\CrySCompileServer\x64\profile.

  2. Start the shader compiler. Don't close the command prompt.

    CrySCompileServer.exe

  3. Open a second command prompt and navigate to the Lumberyard install root directory.

  4. 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.

  5. Copy the shader .pak files generated by the compiler into the game data folder:

    copy build\pc\StarterGame\* %USERPROFILE%\StarterGameRelease\startergame

  6. Generate the game's auxiliary data:

    Tools\Python\python3 BuildReleaseAuxiliaryContent.py --platforms pc --buildFolder Bin64vc142

    The auxiliary data includes configuration information for the engine and game loading and level data.

  7. Copy the auxiliary data to the release directory:

    xcopy /s startergame_pc_paks %USERPROFILE%\StarterGameRelease

Generate game asset bundles

  1. Open a command prompt and navigate to the Lumberyard install root directory.

  2. Bundle assets needed by the game engine: 

    Bin64vc142\AssetBundlerBatch.exe assetLists --addDefaultSeedListFiles --assetListFile engine.assetlist
Bin64vc142\AssetBundlerBatch.exe bundles --assetListFile engine_pc.assetlist --outputBundlePath %USERPROFILE%\StarterGameRelease\startergame\engine.pak

    This generates the engine_pc.pak file in your release folder. The engine pak contains the assets required by the engine and gems.

  3. Bundle game content and level assets: 

    Bin64vc142\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.pak

    This 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 lumberyard_dir\dev\StarterGame. Don't use absolute paths or paths relative to the current directory when adding a seed.

Run your packaged release

  1. Open a command prompt and navigate to your packaged release at %USERPROFILE%\StarterGameRelease.

  2. 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.

Note

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: