Set Up

The engine is setup to compile as a DLL. The basic idea is that the game runs as an application and loads the engine as DLL and uses its functionality.

Setting up a project in C++ can be a pain. To mitigate that I wrote some build scripts with premake, so that with a click you could have your visual studio files, ready to compile with a Starter Scene that is immediately playable.

There are two ways you could use ToyRenderer in your application. Either download the engine from the release and link your project dynamically/implicitly to the dll or pull the engine repo and integrate your project and the engine in the same solution. Of course I have bat files that automate both.

Use the DLL Without the Source Code

Although some might like building the engine themselves and being able to edit the source, others might just want to grab the dll and start making a game without worrying about anything else.

To do that you need to do four things.

1. You need to make sure the dll, and resource folder is placed right next to your executable
2. Add the engine header files include folder to your additional include directories
3. Implicitly link with the ToyRenderer.lib
4. Set up the defines for the project, such as the defines for platform, Debug/Release modes etc.

I would suggest to use post build event to always copy over the resources folder and the dll, wherever you build your project.

I have created a bat file that automates all the above with premake. The release package contains Premake5 and a lua file that creates a project for Visual Studio 2017. All you need to do, is click on GenerateProjectFiles.bat, it asks for a name for the project, give it any name you want (try to avoid spaces for many reasons) and press enter. The build script generates Visual Studio files for you, open the solution folder, build and if everything works, after running the executable created by the build (either from the binaries folder in the solution directory or by running it in visual studio) you should see a standard starter scene.

The starter scene is running in the SandBoxApp.cpp file which should be the only file in your project at this point. In this file there is an example of how an Entry point is defined.

If you wish to configure how the project is setup (change visual studio version or maybe have the engine header files included in the solution) have a look at the content of the .lua and the GenerateProjectFiles bat file.

Engine and Game in One Solution

You might want to have the source code available in your solution. Either as a reference to know what is going on, or because you want to customize the engine. You can make changes, compile the engine and run the game with those changes.

Setting this up is a bit more work than the method above. First you need to get the content of this repo on your computer. For the next steps I have set up a build system with premake to automate the stuff, only the changing of the project name is not automated. Running the GenerateProjectFiles.bat will generate the visual studio files for you, with a SandBox application with a default scene with an example of mesh loading, audio, camera movement and a procedural sky box.

Of course you might want to change the name of the project from SandBox to something else. To do that simply open the premake5.lua file and edit where you see SandBox to your desired project name. Also go to example folder and rename the sandbox folder there to the same name. Generate the project files again, and you will have a starting point for your project with all the stuff setup.

If you look at the lua file you will see some of the stuff that the generatefile does, such as setting up the correct defines for platforms, setting up the additional library directory, linking against the third party applications and adding post build commands for copying over the engine dlls, the resources to your executable every time you compile the engine.

Step by step for the method above:

1. Pull the repository on your machine. You can also donwload as Zip or fork.
2. Open Premake5.Lua file, find and replace where ever you see SandBox with your desired project name.
3. Go to the example folder and rename the folder Sandbox also to your desired name
4. Run GenerateProjectFiles.bat
5. Open the project in Visual Studio 2017 (technically you can open the bat file and generate files for a different IDE or environment however I haven't tested this)
6. Build the solution.
7. If you run the executable, either from the IDE or by running the exe file in ./ToyRenderer-binaries, you should see a scene with camera, skybox, sound and a cube below the grid.

If you get a dll missing error, it is probably because the first time building, it tried to copy the dll as it was still not there. Build again, the second time the dll should be there. To make sure it is actually running the post build event, a change needs to be done to the code to trigger that, add a space somewhere in a cpp file.