Torque includes two build systems - you can choose between the custom-built Project Generator (which goes hand-in-hand with the Project Manager GUI applet), which uses PHP to generate build files, and CMake, which has its own domain-specific language for specifying build dependencies and steps. Take your pick!

Be warned that our CMake support is currently somewhat shaky, and does not work at all with Visual Studio 2008. The project generator is still the preferred solution for generating Windows executables!

In addition, there are still some configuration differences - for example, CMake generates a single executable, while the Project Generator creates a tiny executable and large DLL.

Install prerequisites

In order to compile T3D, you'll need to install the DirectX SDK (June 2010), which you can find here. It is not uncommon to experience an 'error S1023' when attempting to install the SDK. As described here this is due to the wrong version of the VS2010 redistributables being installed on your system. You'll need to uninstall them before proceeding, and the DXSDK setup will reinstall them as part of its own installation.

Generate a project with the Project Generator

The Project Generator is a custom build system written by GarageGames specifically for Torque 3D. It uses PHP scripts to generate solution files for your compiler. It currently supports Visual Studio 2008, 2010, and Unix Makefiles (for dedicated server builds only).

The Project Manager

This page gives you an introduction to using the Project Manager application to set up and configure projects with Torque. If you're not used to using command-line tools then this is the recommended way to manage projects with the project generator!

Project config

You can also edit the modules your project will use manually. In My Projects/Your Project/buildFiles/config are several .conf files. They are all used in different ways when the project generator creates compiler-specific solutions. projectCode.conf is where you should add extensions that apply to all builds across all platforms, rather than being platform-specific.

Using the command-line

To run the project generator manually, without using the Project Manager, ensure you have php in your path and run this command from your project directory:

php ../../Tools/projectGenerator/projectGenerator.php buildFiles/config/project.conf

If you don't have php installed on your system, it's easier to run the generateProjects.bat script, which will use the Windows PHP executables bundled with the engine.

Targeting 64-bit Windows

In order to enable the project to run on 64 bit, a few steps are required.

  1. Go to Build > Configuration Manager.
  2. Under Active Solution Platform, select <New…>
  3. In the pop-up window, change the Type or Select the New Platform field to be x64
  4. Ensure Copy Settings From is set to the Win32 project
  5. Next, on each project in the solution, open their properties, and ensure the Configuration Properties > General > Output Directory and Intermediate Directory fields match the Win32 project's
  6. On the DLL project, go to it's properties, then go to Configuration Properties > Linker > General > Additional Library Directories and change the $(DXSDK_DIR)/Lib/x86 entry to be $(DXSDK_DIR)/Lib/x64
  7. Lastly, go into the DLL project, and remove the asm files from platform/ and math/. They are not currently compatible with a 64bit environment.
  8. Any additional plugins such as physics will need to have the appropriate 64-bit includes and libs as well.
  9. The project is ready to be compiled for 64bit now.

Generate a project with CMake

The CMake gui

Once you've installed CMake, run it and you'll see a screen something like the image below. You'll learn to be pretty familiar with this screen!

The two boxes at the top let you specify the location of your source code and the location to put build files. You should fill them in - the source location is just your regular T3D directory, and the binaries location is where you want your Visual Studio solutions to go. This should probably be something like the image below.

Configuration

Once you've set your paths, you're ready to configure your project! Hit the 'configure' button in the bottom left, and you'll be asked to choose the generator for this project. CMake lets you create project files for many different compilers. Most Windows users will be using some form of Visual Studio, so go ahead and select the version appropriate to you, like in the image below.

Once you've chosen that, you'll be presented with an error message! This is CMake prompting you to enter a name for your project, though unfortunately the only way we have to implement this is by throwing an error!

Don't panic - just hit OK, and expand the 'uncategorized entries' section and edit the value of TORQUE_APP_NAME to match the project name you're working on. At this point you can also specify whether the generated projects should use relative paths. We always recommend doing this.

Once you've filled on those values, hit 'configure' again, and you should be presented with teo more categories - TORQUE and CMAKE. Go ahead and expand TORQUE and browse the options available. You shouldn't need to touch most of these unless you have special needs - for example, PhysX, Bullet, Recast navigation or Oculus Rift support.

Once you're happy with your choices, click 'generate' and CMake will output project files to the directory you chose.

The generated files

If you browse to the location you asked CMake to put your binaries, you'll see something like the image below - a bunch of VS projects and a solution named after your project.

Compiling

To compile your project, open up the solution, right-click the INSTALL project, and click 'build'. You only need to do this the first time - after this compile, you should change the startup project to the one named after your project, and compile and run that.

The engine executable will be generated in the project's game folder (i.e. My Projects/<project name>/game/<project name>.exe).

Using the command-line

cd "C:\Torque3D\My Projects\Game\buildFiles\CMake"

cmake ^
  -G "Visual Studio 12" ^
  -T "v120_xp" ^
  -DTORQUE_APP_NAME="Game" ^
  -DTORQUE_SFX_VORBIS=On ^
  -DTORQUE_THEORA=On ^
  -DCMAKE_BUILD_TYPE=Release ^
  C:\Torque3D

msbuild "Game.sln" /p:PlatformToolset=v120_xp /p:Configuration=Release

Change "Visual Studio 12" to the appropriate generator for your system and 32/64-git requirements.

Targeting Windows XP