DEV Community 👩‍💻👨‍💻


Posted on • Originally published at on

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Settings in usersettings.options can be overridden:

./lmbr_waf.bat build_win_x64_vs2017_profile --enabled-game-projects=SamplesProject
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

        "Interfaces_h": [
Enter fullscreen mode Exit fullscreen mode

Re-generate Visual Studio projects:

# If `generate_vs_projects_automatically` is enabled
./lmbr_waf.bat configure
# Otherwise
./lmbr_waf.bat msvs
Enter fullscreen mode Exit fullscreen mode

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" :
Enter fullscreen mode Exit fullscreen mode
  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
    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 If you are a licensed Sony PlayStation developer, please visit SCE DevNet. Under the Middleware Directory click “Confirm Status” for Amazon Lumberyard.

Top comments (0)

Find what you were looking for? Join hundreds of thousands of developers on DEV so you can:

🌚 Enable dark mode
🔠 Change your default font
📚 Adjust your experience level to see more relevant content