Lumberyard is not as easy to get started with as other game systems, because it is still new, and things change often. With the last update (1.10), it changed the way creating new projects work, to use their gem system.

This tutorial will be only concerned with environment setup, not with coding in particular, and will be for both Visual Studio and Visual Studio Code.

Download and install

The first thing to do, is to go to here, and download Lumberyard. When you run it, the important thing is to check the compiling checkbox in the beginning

After installing the software and the required SDKs, go the the summary section and launch the Configure Project

Configure the Project

In the configuration ui, we need to “Create New” project and give it a name. Then wait awhile as it gets things ready. When finished, you need to set the project as DEFAULT <– very important

Now you can close the configurator.

Next open a command prompt in the install directory’s dev folder (something like c:\Amazon\Lumberyard\1.10.0\dev.) Run lmbr_waf configure.

Build the Project

This is written for either VS2015 or vscode. Note if you want to use VS2017, you need to install 2015 first, and then install 2017. Even though 2017 can include 2015’s compiler, Lumberyard requires certain registry entries to be set up correctly.

So next run lmbr_waf build_win_x64_vs2015_debug -p all in your command prompt. This will take awhile.

While that is compiling, there are a few important things to note.

1. The project folder with settings, including the gems your project needs is located in Lumberyard\1.10.0.0\dev\ (Lumberyard\1.10.0.0\dev\StartingTutorial in my case).
2. 1.10 now gives you a gem to start out with, located in Lumberyard\1.10.0.0\dev\StartingTutorial\Gem where you should put most of your code starting out.
3. The DLL it builds for your gem will be called gem….dll. So mine is Gem.StartingTutorial.6f2c24c30a50422784b2e8c2f362b5dc.v0.1.0.dll.
4. When building for debug, it will put all the built stuff into dev\Bin64vc140.Debug, and when building to run test it will put it in Bin64vc140.Debug.Test. Build for test, you need to run lmbr_waf build_win_x64_vs2015_debug_test -p all

Visual Studio

In your solutions folder (Lumberyard\1.10.0.0\dev\Solutions), open up the LumberyardSDK_vc140 solution with either VS2015 or VS2017.

EDIT: Alex Peterson from Amazon mentioned the following in the slack:
“lmbr_waf has the option to pass a specification as a parameter, so you can say lmbr_waf configure -p game and it will create the solution (Game_vc140.sln) that just has the projects necessary to compile the game which is what Project Configurator is doing behind the scenes. Running lmbr_waf configure uses the “all” spec by default and creates a LumberyardSDK_vc140.sln which has all the projects for compiling editor, engine, game, etc. There is a known issue in 1.10 where if you create a brand new project running lmbr_waf configure won’t regenerate the solution file. You can fix this by running lmbr_waf configure -p all or lmbr_waf msvc -p all.”

(If you open it with 2017, it may ask you to upgrade the projects. Select “No Upgrade”)

In your solution Explorer, you should see something like this:

To launch the game, you will want to make your StartingTutorialWindowsLauncher project the startup project.

To launch the editor, you can go into the Lumberyard\1.10.0\dev\Bin64vc140.Debug folder and run it directly. Make sure you aren’t currently running the launcher when you do this, or the asset manager may get confused.

EDIT: Alex Peterson from Amazon mentioned the following in the slack:
“I think it’s worth mentioning that if you want to compile the editor you need to be sure to select the option Microsoft Foundation Classes when you install VS 2015”
That’s probably why the editor currently doesn’t show up for me in the solution.

Lastly, to get started with the test, you will first need to run lmbr_waf.bat build_win_x64_vs2015_debug_test -p all in a command prompt.

Next, to run test, set the AzTestRunner project as the startup project in VS.

You will need to right click and go into the properties, Go to Debugging, and put in the following Command Arguments.

Gem.StartingTutorial.6f2c24c30a50422784b2e8c2f362b5dc.v0.1.0.dll AzRunUnitTests --pause-on-completion:

You can find your gem’s dll in the Bin64vc140.Debug.Test folder.

Change AzRunUnitTests to be AzRunIntegTests to run your integration test.

If you want a little help starting your first unit test, then you can try out this post, though it is more centered around google mocks than writing a test.

Note that if you are using Visual Studio the best way to add files is:
1. Update the waf file with the new file.
2. Close visual studio
3. Add the files with console, ps, or explorer.
4. Run lmbr_waf configure
5. Open visual studio back up

That’s it for Visual Studio. I suggest trying out setting up basic inputs as the next step.

Visual Studio Code

Unfortunately Visual studio code requires a bit more setup.

I now have a newer alternative setup that I like better.

Why use Visual Studio Code? Good question. Because you hate life… okay not really. Actually vscode has come a long way, and I think in some ways works better for Lumberyard’s waf and testing systems.

VSCODE Setup

First of all, you need to install visual code. When installing, it’s helpful to check the “add to explorer” options.

Next navigate to your Lumberyard\1.10.0.0\dev\\Gem and right click on Code and select “Open With Code.” If you didn’t install that option, then open vscode and select “open folder” to do the same thing.

If you haven’t used vscode before, here’s a quick rundown.

On the left bar, you have:
1. Source with basic explorer functions (create file/folder, rename, etc)
2. Search everywhere
3. Source control (supports a few different types)
4. Debugger
5. Extensions – Shows installed ones until you type something in the search.

Most important command in vscode is to bring up the “command palette”. This is done by hitting F1 or Shift Control P.

Next you need a few extension. Here is my list; some are optional
* C/C++ by Microsoft
* Clipboard History (optional)
* Create Unique Ids (optional but suggested)
* Include Autocomplete (optional but suggested)
* Lumberyard Snippets (optional but written by me :P)
* Power Mode (NOT OPTIONAL MUST HAVE (actually very optional))
* Reloaded C/C++ and Reloaded Themes (optional but suggested) – important: install Reloaded C/C++ first!
* Toggle Header/Source

Be sure to reload the window after each extension. It takes two seconds anyways. (Press F1, type reload, hit enter.) FYI, the C/C++ extension won’t finish installing until you open a header or source file.

Lastly, sets set up our personal settings. Open your user settings through the command palette or by hitting control + comma. Here are mine.. you can change it however you’d like. Note that the settings JSON has intellisense.

{
    "git.confirmSync": false,
    "git.enableSmartCommit": true,
    "powermode.enabled": true,
    "powermode.enableShake": false,
    "powermode.explosionFrequency": 3,
    "powermode.maxExplosions": 10,
    "powermode.explosionSize": 5,
    "powermode.explosionOffset": 0.45,
    "window.zoomLevel": 0,
    "terminal.integrated.shell.windows": "C:\\Windows\\System32\\cmd.exe",
    "editor.renderWhitespace": "all",
    "files.trimTrailingWhitespace": true,
    "workbench.colorTheme": "Reloaded Dark [Default]",
    "files.autoSave": "afterDelay"
}

Lumberyard Setup

This section will be all about setting up vscode’s c/c++ extension to play nice with lumberyard.

Lets start with our workspace settings. Use the command palette; or use control + comma and select workspace at the top right.

Note you can put whatever you want in here, including all your user settings if you’d rather them be project specific.

{
    "C_Cpp.intelliSenseEngine": "Default",
    "C_Cpp.autocomplete": "Default",
    "C_Cpp.errorSquiggles": "Enabled"
}

This will create a settings.json file in a .vscode folder in the folder you opened.

Next we need to set up the c++ configuration file. Select “c/cpp:Edit Configurations” in the command palette (F1). Find the Win32 section at the bottom, and replace it with the following:

{
    "name": "Win32",
    "includePath": [
        "C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/INCLUDE",
        "C:/Program Files (x86)/Windows Kits/10/include/10.0.15063.0/ucrt",
        "${workspaceRoot}/Source",
        "${workspaceRoot}/Include",
        "${workspaceRoot}/../../../Code/CryEngine/CryCommon",
        "${workspaceRoot}/../../../Code/CryEngine/CryAction",
        "${workspaceRoot}/../../../Code/Framework/AzGameFramework",
        "${workspaceRoot}/../../../Code/../Gems/LmbrCentral/Code/include",
        "${workspaceRoot}/../../../Code/Framework/AzFramework",
        "${workspaceRoot}/../../../Code/Framework/GridMate",
        "${workspaceRoot}/../../../Code/Framework/AzCore",
        "${workspaceRoot}/../../../Code/Framework/AzTest",
        "${workspaceRoot}/../../../Code/SDKs/boost",
        "${workspaceRoot}/../../../Code/SDKs/GoogleMock/include"
    ],
    "defines": [
        "_DEBUG",
        "_WIN32",
        "_WIN64",
        "NOMINMAX",
        "CODE_BASE_FOLDER="c:/w/pa/Lumberyard/1.10.0.0/dev/Code/"",
        "_ITERATOR_DEBUG_LEVEL=2",
        "DEDICATED_SERVER",
        "AZ_TESTS_ENABLED",
        "BINFOLDER_NAME="Bin64vc120"",
        "PLATFORM_SUPPORTS_AWS_NATIVE_SDK",
        "LY_BUILD=398643",
        "_MT",
        "_DLL"
    ],
    "intelliSenseMode": "msvc-x64",
    "browse": {
        "path": [
            "C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/INCLUDE",
            "${workspaceRoot}/../../../Code/CryEngine/CryCommon",
            "${workspaceRoot}/Source",
            "${workspaceRoot}/../../../Code/CryEngine/CryAction",
            "${workspaceRoot}/../../../Code/Framework/AzGameFramework",
            "${workspaceRoot}/../../../Code/../Gems/LmbrCentral/Code/include",
            "${workspaceRoot}/../../../Code/Framework/AzFramework",
            "${workspaceRoot}/../../../Code/Framework/GridMate",
            "${workspaceRoot}/../../../Code/Framework/AzCore",
            "${workspaceRoot}/../../../Code/Framework/AzTest",
            "${workspaceRoot}/../../../Code/SDKs/boost",
            "${workspaceRoot}/../../../Code/SDKs/GoogleMock/include"
        ],
        "limitSymbolsToIncludedHeaders": false,
        "databaseFilename": "${workspaceRoot}/.vscode/.BROWSE.VC.DB"
    }
}

This should put a c_cpp_properties.json file in your .vscode folder.

Note that any new includes you may need go into the browse and includePath sections. I also suggest trimming out the ones you do not need for performance reasons. For instance, remove gridMate if you aren’t planning to use multiplayer. Or remove GoogleMock if you are evil and don’t test.

Next thing to set up is the task.json to set up building options

In the .vscode folder, create a file called tasks.json. Here we add our different build options.

You can add as many as you need here, but I’ll give you mine to get you started:

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "0.1.0",
    "options": {
        "cwd": "${cwd}/../../.."
    },
    "runner": "terminal",
    "echoCommand": true,
    "isShellCommand": true,
    "showOutput": "always",
    "tasks": [
        {
            "taskName": "build all",
            "command": "lmbr_waf.bat build_win_x64_vs2015_debug -p all",
            "isBuildCommand": true
        },
        {
            "taskName": "build game",
            "command": "lmbr_waf.bat build_win_x64_vs2015_debug -p game",
            "isBuildCommand": true
        },
        {
            "taskName": "build configure",
            "command": "lmbr_waf.bat",
            "args": [
                "configure"
            ]
        },
        {
            "taskName": "build test",
            "command": "lmbr_waf.bat build_win_x64_vs2015_debug_test -p game",
            "isBuildCommand": true
        },
        {
            "taskName": "build test all",
            "command": "lmbr_waf.bat build_win_x64_vs2015_debug_test -p all",
            "isBuildCommand": true
        }
    ]
}

Anything with an isBuildCommand will come up when you press “Control Shift B” but otherwise you can access all of these by selecting “run task” in the command palette.

Control Shift B will also remember your last selection, so it’s usually enough to do Control + Shift + B, enter, whenever you want to compile.

The final thing to set up is the launcher to debug stuff.

Create a launch.json file in your .vscode folder. Here is mine again. You will have to change it to have your DLL instead of mine, and your launcher name instead of mine.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "launcher",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/../../../Bin64vc140.Debug/TutorialSeriesLauncher.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceRoot}/../../../Bin64vc140.Debug",
            "environment": [],
            "externalConsole": true
        },
        {
            "name": "build & unit",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/../../../Bin64vc140.Debug.Test/AzTestRunner.exe",
            "args": [
                "Gem.StartingTutorial.6f2c24c30a50422784b2e8c2f362b5dc.v0.1.0.dll",
                "AzRunUnitTests",
                "--pause-on-completion",
                "--gtest_break_on_failure"
            ],
            "stopAtEntry": false,
            "cwd": "${workspaceRoot}/../../../Bin64vc140.Debug.Test",
            "environment": [],
            "externalConsole": true,
            "preLaunchTask": "build test"
        },
        {
            "name": "build & integration",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/../../../Bin64vc140.Debug.Test/AzTestRunner.exe",
            "args": [
                "Gem.StartingTutorial.6f2c24c30a50422784b2e8c2f362b5dc.v0.1.0.dll",
                "AzRunIntegTests",
                "--pause-on-completion",
                "--gtest_break_on_failure"
            ],
            "stopAtEntry": false,
            "cwd": "${workspaceRoot}/../../../Bin64vc140.Debug.Test",
            "environment": [],
            "externalConsole": true,
            "preLaunchTask": "build test"
        },
        {
            "name": "unit",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/../../../Bin64vc140.Debug.Test/AzTestRunner.exe",
            "args": [
                "Gem.StartingTutorial.6f2c24c30a50422784b2e8c2f362b5dc.v0.1.0.dll",
                "AzRunUnitTests",
                "--pause-on-completion"
            ],
            "stopAtEntry": false,
            "cwd": "${workspaceRoot}/../../../Bin64vc140.Debug.Test",
            "environment": [],
            "externalConsole": true
        },
        {
            "name": "integration",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/../../../Bin64vc140.Debug.Test/AzTestRunner.exe",
            "args": [
                "Gem.StartingTutorial.6f2c24c30a50422784b2e8c2f362b5dc.v0.1.0.dll",
                "AzRunIntegTests",
                "--pause-on-completion"
            ],
            "stopAtEntry": false,
            "cwd": "${workspaceRoot}/../../../Bin64vc140.Debug.Test",
            "environment": [],
            "externalConsole": true
        },
        {
            "name": "editor",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/../../../Bin64vc140.Debug/Editor.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceRoot}/../../../Bin64vc140.Debug",
            "environment": [],
            "externalConsole": true
        }
    ]
}

Now you should be able to click the debugger icon on the left, and see all these options in the dropdown.

Vscode allows you to put breakpoints, see the stack, variables, watches, threads, etc, though it has some quirkiness and isn’t as fully featured as VS, and definitely not a fully featured as windbg. But it’s good enough for me.

Wrap up

Navigating around visual code is similar to navigating VS with Resharper. Here are my most used keybindings:

• Control p to do fuzzy searches for files
• Control t to fuzzy search symbols (can take some time.)
• Control e for history of files you’ve been to.
• Control Shift v for your clipboard history (if you have the extension.)
• Control Shift B for compiling
• Control D to select multiple things with the same letters you’ve highlighted. (often you rename thing, I just select it, hold down control D to select them all, and then type the new name.)
• Alt Shift Up or Down to duplicate the line up or down.
• See File -> Preferences -> Keyboard Shortcuts for a complete list.

If you are adding a file, it is much easier now. Just add the files where you want them within vscode, then update the waf file. Then run the configure from the command palette (f1 -> run task -> configure, enter).

That’s it for Visual Studio Code. I suggest trying out setting up basic inputs as the next step.

Written By Greg Horvay