Lumberyard and Waf

jeikabu profile image jeikabu Originally published at rendered-obsolete.github.io on ・3 min read

Amazon Lumberyard (3 Part Series)

1) Amazon Lumberyard Intro 2) Lumberyard Builds 3) Lumberyard and Waf

Learning how to work with Lumberyard’s build system is a key part of development. Waf is positioned as a “meta build system”- a framework to make build systems.

Waf Basics

Lumberyard’s build system is extensively documented in the User Guide.

Key files/file-types:

File Description Details
wscript Module script docs
*.waf_files List of files for modules docs
Tools/build/waf-1.x.y/ Build script source code (Python)
_WAF_/specs/ Specs- build configurations with lists of modules spec format

Key commands:

# Help and list of commands
./lmbr_waf.bat --help
# List all commands
./lmbr_waf.bat --list
# GUI to create/edit `dev/_WAF_/usersettings.options`
./lmbr_waf.bat show_option_dialog
# Configure the project using `usersettings.options`
./lmbr_waf.bat configure
# Regenerate Visual Studio solution in `visual_studio_solution_folder` (default: `dev/Solutions/`)
./lmbr_waf.bat msvs

Waf build-related commands follow the format (build|clean|package|deploy)_PLATFORM[_ARCH]_TOOLCHAIN_CONFIG:

./lmbr_waf.bat clean_win_x64_vs2017_profile
# Use _WAF_/specs/engine_and_editor.json spec
./lmbr_waf.bat build_win_x64_vs2017_profile -p engine_and_editor
./lmbr_waf.bat build_win_x64_vs2017_profile --project-spec=engine_and_editor

Settings in usersettings.options can be overridden:

./lmbr_waf.bat build_win_x64_vs2017_profile --enabled-game-projects=SamplesProject

Adding/Removing a File

Check the project’s wscript for the list of files. Here’s Code\CryEngine\CryCommon\wscript:

def build(bld):
        # SNIP
        target = 'CryCommon',
        vs_filter = 'Common',
        file_list = 'crycommon.waf_files',
        # SNIP

crycommon.waf_files is json specifying the files and VS solution filters:

        "Interfaces_h": [

Re-generate Visual Studio projects:

# If `generate_vs_projects_automatically` is enabled
./lmbr_waf.bat configure
# Otherwise
./lmbr_waf.bat msvs

Creates a solution with a Common filter containing a “CryCommon” project with QTangent.h in the root and a Interfaces_h sub-filter:

Adding a Spec

It’s easy to create a new spec to only build a particular subset of modules. The Lumberyard User Guide has good documentation:

For example, we can create a spec to build the editor plugins- which are otherwise only built with the all spec.

  1. Create _WAF_/specs/editor_plugins.json:
     "description": "Editor Plugins",
     "visual_studio_name": "Editor Plugins",

     "modules" :
  1. Add the new spec to specs_to_include_in_project_generation: via Visual Studio Project Generator tab of ./lmbr_waf.bat show_option_dialog. Or, in _WAF_/user_settings.options:

    [Visual Studio Project Generator]
    specs_to_include_in_project_generation = all,editor_plugins
  2. Generate Visual Studio files:

    ./lmbr_waf.bat msvs
    # Or, if `generate_vs_projects_automatically` is enabled
    ./lmbr_waf.bat configure
  3. Build: select [Editor Plugins] configuration in Visual Studio. Or:

    ./lmbr_waf.bat build_win_x64_vs2017_profile -p editor_plugins


With Lumberyard 1.21 released, now is also a good time to walk through a simple engine upgrade.

  1. Update git repo

    # Assumes you're working on a fork. If not, skip this and replace `upsteam` with `origin`
    git remote add upstream https://github.com/aws/lumberyard.git
    git fetch --all
    git checkout master
    git pull upstream master
  2. Optionally, if you subscribe to the “nuke it from orbit” school of thought:

    Remove-Item -Recurse -Path ./dev,./3rdParty
    # Restore dev/ and 3rdParty/
    git reset --hard
    # Remove untracked files/directories
    git clean -fd
  3. Update binaries and 3rd-party dependencies

    # If it doesn't start automatically
  4. Re-initialize Waf

    cd dev/
    ./lmbr_waf.bat configure


  • The configurations have rather long names. You can embiggen the Solution Configurations drop-down (from here):

    1. Tools > Customize…
    2. Commands tab, Toolbar : “Standard”
    3. In Preview: select Solution Configurations
    4. Click Modify Selection button
    5. Here’s Width of 150 :
  • If you’re a licensed Playstation/Xbox developer you can get access to Lumberyard PS4/Xbone code (from the FAQ):

    If you are a licensed Microsoft Xbox developer, please e-mail your name, studio name, and the licensed e-mail address to lumberyard-consoles@amazon.com. If you are a licensed Sony PlayStation developer, please visit SCE DevNet. Under the Middleware Directory click “Confirm Status” for Amazon Lumberyard.

Amazon Lumberyard (3 Part Series)

1) Amazon Lumberyard Intro 2) Lumberyard Builds 3) Lumberyard and Waf

Posted on by:


markdown guide