Getting Started with Lumberyard 1.11 and C++

The new version of lumberyard was released! Yaaaay. With it came many huge features such as EmotionFX (professional animation studio) and Script Canvas (visual scripting.) Basically, this (version) changes… everything.

People who have used both CryEngine’s animation tool (mannequin) and EmotionFX seem to really like the release. In fact, they have been known to say that they used to have Mannequin Depression, but then they got their EmotionFix.

This tutorial will go through none of that, however. I know, disappointed.

Things have changed in starting a new project. A lot of boiler plate code was removed to make things simpler.

Also, since my first tutorial on setting up the environment, something amazing happened: GIIITHUUUUUUUUB!!!!!!111one. Honestly though, what’s up with that 30% of the code is python, huh? Should be like 113% C++ and like -24% python, but I guess we have to live in the real world with real laws of math.

Getting Started With Git

Last time we used the installer to get Lumberyard, but that’s super lame and probably the original reason the dinosaurs died (or maybe they just got too fat and died.)

If you already know what client you are using and where you want your repo to live, you can skip to the next chapter.

So this time we are going to git ‘er done with Github. This means you will need some git client. Here are some suggestions.

During instillation, be sure to enable the command line tools.

Whatever you choose, I’m going to use the command line version. However, you can use the GUIs to do the same thing.

Next you need to decide where you want to put your Repository, where you will need to create an account. Here are 3 common places:

The advantage of Github is that it is the easiest to use. However, Bitbucket and VSO allow private repositories for free (ie, no one else can see them.)

For this tutorial, we will use Github. If you are too, be sure to create an account there.

Fork (because there is no spoon – sorry) the Lumberyard Git Repository!

Wouldn’t it be ironic if our robots overlords created a fork of The Matrix, since the Matrix has no spoons. Wait, no, that would make it totally appropriate.

Anyway, fork that nonsense, lets fork Lumberyard. Go here and click the fork button at the top right. Select your account if it ask.
tut_setup_1_11_fork

Now you should see something like this:
tut_setup_1_11_afterfork

Congratz, you are now the proud owner of a beautiful new repository (it may be a used repo, but it’s your repo.)

Note that you can change the name of your repository from Lumberyard to something else like “FredsUsedLumber” in the settings tab.

Cloning Your Repository to Your Local Computer

Don’t be tempted by the likeness of the words Repository and Suppository. They have completely different meanings and honestly don’t even make good metaphors to describe each other (as long as you don’t look up certain git arguments like git push --set-upstream and then have to use git --force)

So, to clone our suppository, er, I mean, Repository, we first need to create a place on our computer to put it. You want to make sure the path is not too long, because (at least with previous versions) the paths of things can get too long for some processes. Something like c:\work should be good.

Next open up a command prompt and navigate to that folder cd c:\work. Now it’s time to do the cloning. Here is the command for my fork: git clone https://github.com/horvay/lumberyardtutor. You can get your url by copy and pasting the URL in github. This will copy everything from your repo in Github to your local computer.

At this point our git stuff is finished. If you want to learn more about Git and how to use it, I suggest googling it.

With this setup, it will make updating your Lumberyard version easier in the future. But doing this is for a future tutorial.

Run the Bootstrapper and Setup

As it says on the Github, you need to next run the git_bootstrap.exe program located in the folder your cloned your stuff into.

You will see something like this. Push any key, dummy.
tut_setup_1_11_bootstraper

This is going to download a lot of the dependencies (even if G.I.Joe says to stop all the downloading). Once it finishes, it should automagically launch the setup assistant. If for whatever reason you want to run the setup assistant manually, it can be found at dev\Tools\LmbrSetup\Win\SetupAssistant.exe.

When it loads, be sure to select custom installation. After that, select the following options:
tut_setup_1_11_compile_options

In the next few steps, you need to install all the required SDKs. Once you make it to the summary step, click the Configure Project button. This brings up the Project Configurator.

From here you can click “Create New”. Put in a name for your project, and select “Default” (unless you are a pro – like a boss.) Hit “Create Project”, and wait awhile.

VERY IMPORTANT. EL IMPORTANTE. Once it finishes, click your new project, and select “Set as Default”.

Minor Note

Oh, one last thing. If you commit your new project to Github, and then check it out on another computer, you’ll get an issue requiring lots of tissues. It will fail to compile. This is because the compilation process uses an ico file that is being ignored by default.

In fact, I found a few issues with the .gitignore file. I have a request for them to update it here.

For now you can use my .gitignore file:

.gitignore:

# Ignore every file.
*

# Except for all other directories & subdirectories
!**/

# In every subdirectory, avoid ignoring files with the following extensions.
!**/*.[cC][pP][pP]
!**/*.[hH]
!**/*.args
!**/*.asp
!**/*.attribute_layout
!**/*.bat
!**/*.c
!**/*.cbc
!**/*.cfg
!**/*.chrparams
!**/*.cmake
!**/*.cmd
!**/*.conf
!**/*.coffee
!**/*.cpp
!**/*.cs
!**/*.csproj
!**/*.decTest
!**/*.def
!**/*.ent
!**/*.ent_template
!**/*.env
!**/*.exportsettings
!**/*.filters
!**/*.h
!**/*.hpp
!**/*.html
!**/*.hxx
!**/*.ico
!**/*.ignore
!**/*.ini
!**/*.inl
!**/*.java
!**/*.js
!**/*.json
!**/*.lua
!**/*.lua_template
!**/*.lyr
!**/*.m
!**/*.manifest
!**/*.md
!**/*.mel
!**/*.mm
!**/*.mk
!**/*.ms
!**/*.mtl
!**/*.npmignore
!**/*.p4ignore
!**/*.plist
!**/*.prefab
!**/*.pro
!**/*.props
!**/*.py
!**/*.pyproj
!**/*.pys
!**/*.pyw
!**/*.qml
!**/*.qmldir
!**/*.qmltypes
!**/*.qrc
!**/*.qss
!**/*.rc
!**/*.sct
!**/*.sh
!**/*.slice
!**/*.sln
!**/*.spec
!**/*.sql
!**/*.targets
!**/*.tcl
!**/*.tip
!**/*.[tT][xX][tT]
!**/*.ui
!**/*.uicanvas
!**/*.vbs
!**/*.vcproj
!**/*.vcxproj
!**/*.vssscc
!**/*.waf_files
!**/*.xbm
!**/*.xml
!**/ChangeLog
!**/configure
!**/DEVEL
!**/lmbr_waf
!**/[mM]akefile
!**/makefile.appletv
!**/wscript
!**/README
!**/TODO
!**/waf

# Make an exception to ignore specific directories
# Most of these directories are brought in by executing git_bootstrap.
/3rdParty
/dev/AssetProcessorTemp
/dev/BinTemp
/dev/Bin64
/dev/Bin64vc120
/dev/Bin64vc140
/dev/Bin64vc140.Debug
/dev/Cache
/dev/FeatureTests
/dev/SamplesProject
/dev/Code/SDKs
/dev/Code/Sandbox/SDKs
/dev/Solutions
/dev/Code/Tools/SDKs
/dev/MultiplayerSample
/dev/MultiplayerProject
/dev/Gems/GameEffectSystem
/dev/Gems/Oculus
/dev/Gems/OpenVR
/dev/Gems/PBSreferenceMaterials
/dev/Gems/Substance
/dev/Tools/CrySCompileServer/x64
/dev/Tools/LmbrSetup/Win.vc140.Debug

# Ignore ico files from Lumberyard folders but preserve ico files in project folders
/dev/Code/**/*.ico
/dev/CloudGemSamples/**/*.ico
/dev/Tools/**/*.ico

# Misc ignore files
/dev/SetupAssistantUserPreferences.ini
/dev/_WAF_/environment.json
/SetupAssistant.bat

So Many Solutions, so Little Time

Peanut butter solution time! The Visual Studio solutions are found in dev\Solutions. You should see 3 of them at least (like Goldilocks on that fateful day.)

  1. LumberyardSDK_vc140.sln This solution contains a lot of the engine and other stuff. Honestly, this can make everything slow moving, and cold, due to it’s size. So I don’t use it unless I need something from it.
  2. [Project Name]_vc140.sln This solution is the minimal solution for your game. It includes all the Gems your game uses, and some engine high level stuff. If you need the smallest solution, this is for you, but for me, it runs too hot.
  3. Game_vc140.sln This solution is similar to the one above, except it also includes CryAction, which is still used in Lumberyard sometimes. It’s temperature is perfect.

Another config to know about is the dev \ _WAF_\user_settings.options. If you want to fine tune what projects are included in your solution, you can define the super-set of possible things to include here.

Removing things from the following line will make them not be included in any sln file.

user_settings.options:

specs_to_include_in_project_generation = all, game, game_and_engine, resource_compiler

For instance, if you remove everything except “game”, your Lumberyard_vc140.sln will be the same as your Game_vc140.sln.

So lets open the Game_vc140.sln

Understanding the Solution

If anyone ask you if you got “game”, know they are totally talking about the game_vc140.sln file. If you show them your knowledge of it, they will think you got “game”… like, totally.

The first sections in the solution are framework projects that are either written by Lumberyard or still commonly used CryEngine stuff.

tut_setup_1_11_framework_stuff.png

The next section is the Gems that your project uses. These can be selected/deselected in the Project Configurator.

tut_setup_1_11_solution_gems

These can also be modified in your gems.json file (dev\[Project Name]\gems.json); however, if you want to use them in your c++ code, you will also need to add them to dev\[Project Name]\Gem\gem.json as a dependency, something like:

dev\TutorialSeries\Gem\gem.json:

{
    "Dependencies": [
        {
            "Uuid": "ff06785f7145416b9d46fde39098cb0c",
            "VersionConstraints": [
                "~>0.1"
            ],
            "_comment": "LmbrCentral"
        }
    ],
    "GemFormatVersion": 3,
    "Uuid": "7a17c44ce76744e1b646e6d8556372c8",
    "Name": "TutorialSeries",
    "DisplayName": "TutorialSeries",
    "Version": "0.1.0",
    "LinkType": "Dynamic",
    "Summary": "A short description of my Game Project Gem.",
    "Tags": ["Game"],
    "IconPath": "preview.png",
    "IsGameGem": true
}

The Uuid comes from the dev\Gems\LmbrCentral\gem.json config file.

The next section is the launchers for the game. These are probably going to be your most common startup programs. (Right click and set as Startup Project.)

tut_setup_1_11_Launchers

The rest of it.

tut_setup_1_11_TheRest

The Network folder has GridMate which is Lumberyard’s multiplayer networking solution.

Next is the Editor Projects. This is just a subset of the editor code. If you want to see it all, then check out the Sandbox folder in the Lumberyard_vc140.sln file. There you can also make the “Editor” project the startup project and debug the editor.

The next project involves the asset processor. It’s not the whole code base for it by any means. The asset processor automagically runs in the background to process your game’s assets into something that engine can interpret in a speedy manner.

Lastly (at least in my screenshot) is TutorialUI, which is the name of the project I made. We’ll look more at this later.

Build Configurations

In one of the solutions, click the Build Configuration dropdown.
tut_setup_1_11_Build_configurations

You will see a lot of options here. You’ll also notice the dropdown itself is painfully small and you can’t really tell what in tarnation is selected.

Lets first increase the size of this dropdown. Click the doohickey on the toolbar, that looks like a thingamajigger
tut_setup_1_11_thingamajigger

Select “Add or Remove Buttons” and then “Customize”. Click the actual dropdown in the bottom left image, and click “Modify Selection.” There you should be able to change the width to something over 9000 (I mean 200 or so.)
tut_setup_1_11_width

Lets go through the build configurations:

  1. Debug – This is the main configuration to use if you want to debug your game. This gets outputted to the ‘dev\Bin64vc140.Debug’ folder.
  2. Profile – This is good if you aren’t stepping through code and debugging. It’s faster than Debug, and better for running the editor. This gets outputted to the ‘dev\Bin64vc140’ folder.
  3. Performance – No freakin’ clue.
  4. Release – Don’t mess with this if you are starting out. You have to do a lot more to release something in Lumberyard than selecting this option anyway.

If you open the Lumberyard_vc140.sln, you will notice all the same options duplicated: once for “game” and again for “all.” This may be sorta crazy talk, but “game” compiles your game code and supporting libraries only, and “all” compiles everything (editor, asset processor, game, etc.)

A Look at the Project

Now lets look at the project we created.

tut_setup_1_11_project

The import files here are [Project Name]SystemComponent.h/cpp. Lumberyard gave us this system component to start with.

At this point, you are almost ready to start with either the FPS input tutorial series or the RTS camera tutorial series.

However, in those series, we use a file that doesn’t exist anymore, because Lumberyard cleaned up some CryPoo ™. In those tutorials, we automatically load the map we want in the GameStartup.cpp file, which you may notice doesn’t exist anymore. Luckily we can do this with a config file now.

Create a file in your project folder called autoexec.cfg (dev \ [Project Name]\autoexec.cfg).

autoexec.cfg:

map TutorialLevel

(It’s a small file)

Projects will automatically run anything in that file on startup after some of the framework has been loaded.

Note, that you will need to first create a Level called TutorialLevel, which is done in one of the aforementioned tutorials.

The rest of the FPS and RTS tutorials should be good.

Conclusion

I hope this gives you a good start on building a Lumberyard game in 1.11. If you become big and famous, be sure to say something nice. Maybe if you get your Hollywood star, you can use my hand-print with it. Or maybe just use my name instead of yours.

Or you could just send a check to my offshore bank account. Or maybe you can support my brother in spirit.

Either way, keep on coding, and remember: haters gonna hate, and ain’ters gonna ain’t.

2 thoughts on “Getting Started with Lumberyard 1.11 and C++

  1. Great stuff, thanks for the tutorial! One question: I only get the very cold, all-inclusive solution, not the hotter ones. Is there a special configuration step or command that I have to execute?

    Like

    1. Sorry I didn’t reply sooner! Somehow I missed the notification.

      That is strange. I’d suggest trying to run lmbr_waf configure -p game to see if it creates your game solution. Or lmbr_waf configure -p [your project name] for the 3rd one.

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s